chore: version packages

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.agents/skills/remotion-best-practices/SKILL.md

@@ -1,61 +0,0 @@
----
-name: remotion-best-practices
-description: Best practices for Remotion - Video creation in React
-metadata:
-  tags: remotion, video, react, animation, composition
----
-
-## When to use
-
-Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
-
-## Captions
-
-When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
-
-## Using FFmpeg
-
-For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./rules/ffmpeg.md](./rules/ffmpeg.md) file for more information.
-
-## Audio visualization
-
-When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./rules/audio-visualization.md](./rules/audio-visualization.md) file for more information.
-
-## Sound effects
-
-When needing to use sound effects, load the [./rules/sound-effects.md](./rules/sound-effects.md) file for more information.
-
-## How to use
-
-Read individual rule files for detailed explanations and code examples:
-
-- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
-- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
-- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
-- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
-- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
-- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
-- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion (bar, pie, line, stock charts)
-- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
-- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
-- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
-- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
-- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
-- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
-- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
-- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
-- [rules/light-leaks.md](rules/light-leaks.md) - Light leak overlay effects using @remotion/light-leaks
-- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
-- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
-- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
-- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
-- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
-- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
-- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
-- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
-- [rules/transparent-videos.md](rules/transparent-videos.md) - Rendering out a video with transparency
-- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
-- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch
-- [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
-- [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it
-- [rules/voiceover.md](rules/voiceover.md) - Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS

.agents/skills/remotion-best-practices/rules/3d.md

@@ -1,86 +0,0 @@
----
-name: 3d
-description: 3D content in Remotion using Three.js and React Three Fiber.
-metadata:
-  tags: 3d, three, threejs
----
-
-# Using Three.js and React Three Fiber in Remotion
-
-Follow React Three Fiber and Three.js best practices.  
-Only the following Remotion-specific rules need to be followed:
-
-## Prerequisites
-
-First, the `@remotion/three` package needs to be installed.  
-If it is not, use the following command:
-
-```bash
-npx remotion add @remotion/three # If project uses npm
-bunx remotion add @remotion/three # If project uses bun
-yarn remotion add @remotion/three # If project uses yarn
-pnpm exec remotion add @remotion/three # If project uses pnpm
-```
-
-## Using ThreeCanvas
-
-You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
-`<ThreeCanvas>` MUST have a `width` and `height` prop.
-
-```tsx
-import { ThreeCanvas } from "@remotion/three";
-import { useVideoConfig } from "remotion";
-
-const { width, height } = useVideoConfig();
-
-<ThreeCanvas width={width} height={height}>
-  <ambientLight intensity={0.4} />
-  <directionalLight position={[5, 5, 5]} intensity={0.8} />
-  <mesh>
-    <sphereGeometry args={[1, 32, 32]} />
-    <meshStandardMaterial color="red" />
-  </mesh>
-</ThreeCanvas>;
-```
-
-## No animations not driven by `useCurrentFrame()`
-
-Shaders, models etc MUST NOT animate by themselves.  
-No animations are allowed unless they are driven by `useCurrentFrame()`.  
-Otherwise, it will cause flickering during rendering.
-
-Using `useFrame()` from `@react-three/fiber` is forbidden.
-
-## Animate using `useCurrentFrame()`
-
-Use `useCurrentFrame()` to perform animations.
-
-```tsx
-const frame = useCurrentFrame();
-const rotationY = frame * 0.02;
-
-<mesh rotation={[0, rotationY, 0]}>
-  <boxGeometry args={[2, 2, 2]} />
-  <meshStandardMaterial color="#4a9eff" />
-</mesh>;
-```
-
-## Using `<Sequence>` inside `<ThreeCanvas>`
-
-The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
-
-```tsx
-import { Sequence } from "remotion";
-import { ThreeCanvas } from "@remotion/three";
-
-const { width, height } = useVideoConfig();
-
-<ThreeCanvas width={width} height={height}>
-  <Sequence layout="none">
-    <mesh>
-      <boxGeometry args={[2, 2, 2]} />
-      <meshStandardMaterial color="#4a9eff" />
-    </mesh>
-  </Sequence>
-</ThreeCanvas>;
-```

.agents/skills/remotion-best-practices/rules/animations.md

@@ -1,27 +0,0 @@
----
-name: animations
-description: Fundamental animation skills for Remotion
-metadata:
-  tags: animations, transitions, frames, useCurrentFrame
----
-
-All animations MUST be driven by the `useCurrentFrame()` hook.  
-Write animations in seconds and multiply them by the `fps` value from `useVideoConfig()`.
-
-```tsx
-import { useCurrentFrame } from "remotion";
-
-export const FadeIn = () => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-
-  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
-    extrapolateRight: "clamp",
-  });
-
-  return <div style={{ opacity }}>Hello World!</div>;
-};
-```
-
-CSS transitions or animations are FORBIDDEN - they will not render correctly.  
-Tailwind animation class names are FORBIDDEN - they will not render correctly.

.agents/skills/remotion-best-practices/rules/assets.md

@@ -1,78 +0,0 @@
----
-name: assets
-description: Importing images, videos, audio, and fonts into Remotion
-metadata:
-  tags: assets, staticFile, images, fonts, public
----
-
-# Importing assets in Remotion
-
-## The public folder
-
-Place assets in the `public/` folder at your project root.
-
-## Using staticFile()
-
-You MUST use `staticFile()` to reference files from the `public/` folder:
-
-```tsx
-import { Img, staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return <Img src={staticFile("logo.png")} />;
-};
-```
-
-The function returns an encoded URL that works correctly when deploying to subdirectories.
-
-## Using with components
-
-**Images:**
-
-```tsx
-import { Img, staticFile } from "remotion";
-
-<Img src={staticFile("photo.png")} />;
-```
-
-**Videos:**
-
-```tsx
-import { Video } from "@remotion/media";
-import { staticFile } from "remotion";
-
-<Video src={staticFile("clip.mp4")} />;
-```
-
-**Audio:**
-
-```tsx
-import { Audio } from "@remotion/media";
-import { staticFile } from "remotion";
-
-<Audio src={staticFile("music.mp3")} />;
-```
-
-**Fonts:**
-
-```tsx
-import { staticFile } from "remotion";
-
-const fontFamily = new FontFace("MyFont", `url(${staticFile("font.woff2")})`);
-await fontFamily.load();
-document.fonts.add(fontFamily);
-```
-
-## Remote URLs
-
-Remote URLs can be used directly without `staticFile()`:
-
-```tsx
-<Img src="https://example.com/image.png" />
-<Video src="https://remotion.media/video.mp4" />
-```
-
-## Important notes
-
-- Remotion components (`<Img>`, `<Video>`, `<Audio>`) ensure assets are fully loaded before rendering
-- Special characters in filenames (`#`, `?`, `&`) are automatically encoded

.agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx

@@ -1,173 +0,0 @@
-import {loadFont} from '@remotion/google-fonts/Inter';
-import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
-
-const {fontFamily} = loadFont();
-
-const COLOR_BAR = '#D4AF37';
-const COLOR_TEXT = '#ffffff';
-const COLOR_MUTED = '#888888';
-const COLOR_BG = '#0a0a0a';
-const COLOR_AXIS = '#333333';
-
-// Ideal composition size: 1280x720
-
-const Title: React.FC<{children: React.ReactNode}> = ({children}) => (
-	<div style={{textAlign: 'center', marginBottom: 40}}>
-		<div style={{color: COLOR_TEXT, fontSize: 48, fontWeight: 600}}>
-			{children}
-		</div>
-	</div>
-);
-
-const YAxis: React.FC<{steps: number[]; height: number}> = ({
-	steps,
-	height,
-}) => (
-	<div
-		style={{
-			display: 'flex',
-			flexDirection: 'column',
-			justifyContent: 'space-between',
-			height,
-			paddingRight: 16,
-		}}
-	>
-		{steps
-			.slice()
-			.reverse()
-			.map((step) => (
-				<div
-					key={step}
-					style={{
-						color: COLOR_MUTED,
-						fontSize: 20,
-						textAlign: 'right',
-					}}
-				>
-					{step.toLocaleString()}
-				</div>
-			))}
-	</div>
-);
-
-const Bar: React.FC<{
-	height: number;
-	progress: number;
-}> = ({height, progress}) => (
-	<div
-		style={{
-			flex: 1,
-			display: 'flex',
-			flexDirection: 'column',
-			justifyContent: 'flex-end',
-		}}
-	>
-		<div
-			style={{
-				width: '100%',
-				height,
-				backgroundColor: COLOR_BAR,
-				borderRadius: '8px 8px 0 0',
-				opacity: progress,
-			}}
-		/>
-	</div>
-);
-
-const XAxis: React.FC<{
-	children: React.ReactNode;
-	labels: string[];
-	height: number;
-}> = ({children, labels, height}) => (
-	<div style={{flex: 1, display: 'flex', flexDirection: 'column'}}>
-		<div
-			style={{
-				display: 'flex',
-				alignItems: 'flex-end',
-				gap: 16,
-				height,
-				borderLeft: `2px solid ${COLOR_AXIS}`,
-				borderBottom: `2px solid ${COLOR_AXIS}`,
-				paddingLeft: 16,
-			}}
-		>
-			{children}
-		</div>
-		<div
-			style={{
-				display: 'flex',
-				gap: 16,
-				paddingLeft: 16,
-				marginTop: 12,
-			}}
-		>
-			{labels.map((label) => (
-				<div
-					key={label}
-					style={{
-						flex: 1,
-						textAlign: 'center',
-						color: COLOR_MUTED,
-						fontSize: 20,
-					}}
-				>
-					{label}
-				</div>
-			))}
-		</div>
-	</div>
-);
-
-export const MyAnimation = () => {
-	const frame = useCurrentFrame();
-	const {fps, height} = useVideoConfig();
-
-	const data = [
-		{month: 'Jan', price: 2039},
-		{month: 'Mar', price: 2160},
-		{month: 'May', price: 2327},
-		{month: 'Jul', price: 2426},
-		{month: 'Sep', price: 2634},
-		{month: 'Nov', price: 2672},
-	];
-
-	const minPrice = 2000;
-	const maxPrice = 2800;
-	const priceRange = maxPrice - minPrice;
-	const chartHeight = height - 280;
-	const yAxisSteps = [2000, 2400, 2800];
-
-	return (
-		<AbsoluteFill
-			style={{
-				backgroundColor: COLOR_BG,
-				padding: 60,
-				display: 'flex',
-				flexDirection: 'column',
-				fontFamily,
-			}}
-		>
-			<Title>Gold Price 2024</Title>
-
-			<div style={{display: 'flex', flex: 1}}>
-				<YAxis steps={yAxisSteps} height={chartHeight} />
-				<XAxis height={chartHeight} labels={data.map((d) => d.month)}>
-					{data.map((item, i) => {
-						const progress = spring({
-							frame: frame - i * 5 - 10,
-							fps,
-							config: {damping: 18, stiffness: 80},
-						});
-
-						const barHeight =
-							((item.price - minPrice) / priceRange) * chartHeight * progress;
-
-						return (
-							<Bar key={item.month} height={barHeight} progress={progress} />
-						);
-					})}
-				</XAxis>
-			</div>
-		</AbsoluteFill>
-	);
-};

.agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx

@@ -1,100 +0,0 @@
-import {
-	AbsoluteFill,
-	interpolate,
-	useCurrentFrame,
-	useVideoConfig,
-} from 'remotion';
-
-const COLOR_BG = '#ffffff';
-const COLOR_TEXT = '#000000';
-const FULL_TEXT = 'From prompt to motion graphics. This is Remotion.';
-const PAUSE_AFTER = 'From prompt to motion graphics.';
-const FONT_SIZE = 72;
-const FONT_WEIGHT = 700;
-const CHAR_FRAMES = 2;
-const CURSOR_BLINK_FRAMES = 16;
-const PAUSE_SECONDS = 1;
-
-// Ideal composition size: 1280x720
-
-const getTypedText = ({
-	frame,
-	fullText,
-	pauseAfter,
-	charFrames,
-	pauseFrames,
-}: {
-	frame: number;
-	fullText: string;
-	pauseAfter: string;
-	charFrames: number;
-	pauseFrames: number;
-}): string => {
-	const pauseIndex = fullText.indexOf(pauseAfter);
-	const preLen =
-		pauseIndex >= 0 ? pauseIndex + pauseAfter.length : fullText.length;
-
-	let typedChars = 0;
-	if (frame < preLen * charFrames) {
-		typedChars = Math.floor(frame / charFrames);
-	} else if (frame < preLen * charFrames + pauseFrames) {
-		typedChars = preLen;
-	} else {
-		const postPhase = frame - preLen * charFrames - pauseFrames;
-		typedChars = Math.min(
-			fullText.length,
-			preLen + Math.floor(postPhase / charFrames),
-		);
-	}
-	return fullText.slice(0, typedChars);
-};
-
-const Cursor: React.FC<{
-	frame: number;
-	blinkFrames: number;
-	symbol?: string;
-}> = ({frame, blinkFrames, symbol = '\u258C'}) => {
-	const opacity = interpolate(
-		frame % blinkFrames,
-		[0, blinkFrames / 2, blinkFrames],
-		[1, 0, 1],
-		{extrapolateLeft: 'clamp', extrapolateRight: 'clamp'},
-	);
-
-	return <span style={{opacity}}>{symbol}</span>;
-};
-
-export const MyAnimation = () => {
-	const frame = useCurrentFrame();
-	const {fps} = useVideoConfig();
-
-	const pauseFrames = Math.round(fps * PAUSE_SECONDS);
-
-	const typedText = getTypedText({
-		frame,
-		fullText: FULL_TEXT,
-		pauseAfter: PAUSE_AFTER,
-		charFrames: CHAR_FRAMES,
-		pauseFrames,
-	});
-
-	return (
-		<AbsoluteFill
-			style={{
-				backgroundColor: COLOR_BG,
-			}}
-		>
-			<div
-				style={{
-					color: COLOR_TEXT,
-					fontSize: FONT_SIZE,
-					fontWeight: FONT_WEIGHT,
-					fontFamily: 'sans-serif',
-				}}
-			>
-				<span>{typedText}</span>
-				<Cursor frame={frame} blinkFrames={CURSOR_BLINK_FRAMES} />
-			</div>
-		</AbsoluteFill>
-	);
-};

.agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx

@@ -1,103 +0,0 @@
-import {loadFont} from '@remotion/google-fonts/Inter';
-import React from 'react';
-import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
-
-/*
- * Highlight a word in a sentence with a spring-animated wipe effect.
- */
-
-// Ideal composition size: 1280x720
-
-const COLOR_BG = '#ffffff';
-const COLOR_TEXT = '#000000';
-const COLOR_HIGHLIGHT = '#A7C7E7';
-const FULL_TEXT = 'This is Remotion.';
-const HIGHLIGHT_WORD = 'Remotion';
-const FONT_SIZE = 72;
-const FONT_WEIGHT = 700;
-const HIGHLIGHT_START_FRAME = 30;
-const HIGHLIGHT_WIPE_DURATION = 18;
-
-const {fontFamily} = loadFont();
-
-const Highlight: React.FC<{
-	word: string;
-	color: string;
-	delay: number;
-	durationInFrames: number;
-}> = ({word, color, delay, durationInFrames}) => {
-	const frame = useCurrentFrame();
-	const {fps} = useVideoConfig();
-
-	const highlightProgress = spring({
-		fps,
-		frame,
-		config: {damping: 200},
-		delay,
-		durationInFrames,
-	});
-	const scaleX = Math.max(0, Math.min(1, highlightProgress));
-
-	return (
-		<span style={{position: 'relative', display: 'inline-block'}}>
-			<span
-				style={{
-					position: 'absolute',
-					left: 0,
-					right: 0,
-					top: '50%',
-					height: '1.05em',
-					transform: `translateY(-50%) scaleX(${scaleX})`,
-					transformOrigin: 'left center',
-					backgroundColor: color,
-					borderRadius: '0.18em',
-					zIndex: 0,
-				}}
-			/>
-			<span style={{position: 'relative', zIndex: 1}}>{word}</span>
-		</span>
-	);
-};
-
-export const MyAnimation = () => {
-	const highlightIndex = FULL_TEXT.indexOf(HIGHLIGHT_WORD);
-	const hasHighlight = highlightIndex >= 0;
-	const preText = hasHighlight ? FULL_TEXT.slice(0, highlightIndex) : FULL_TEXT;
-	const postText = hasHighlight
-		? FULL_TEXT.slice(highlightIndex + HIGHLIGHT_WORD.length)
-		: '';
-
-	return (
-		<AbsoluteFill
-			style={{
-				backgroundColor: COLOR_BG,
-				alignItems: 'center',
-				justifyContent: 'center',
-				fontFamily,
-			}}
-		>
-			<div
-				style={{
-					color: COLOR_TEXT,
-					fontSize: FONT_SIZE,
-					fontWeight: FONT_WEIGHT,
-				}}
-			>
-				{hasHighlight ? (
-					<>
-						<span>{preText}</span>
-						<Highlight
-							word={HIGHLIGHT_WORD}
-							color={COLOR_HIGHLIGHT}
-							delay={HIGHLIGHT_START_FRAME}
-							durationInFrames={HIGHLIGHT_WIPE_DURATION}
-						/>
-						<span>{postText}</span>
-					</>
-				) : (
-					<span>{FULL_TEXT}</span>
-				)}
-			</div>
-		</AbsoluteFill>
-	);
-};

.agents/skills/remotion-best-practices/rules/audio-visualization.md

@@ -1,198 +0,0 @@
----
-name: audio-visualization
-description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
-metadata:
-  tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
----
-
-# Audio Visualization in Remotion
-
-## Prerequisites
-
-```bash
-npx remotion add @remotion/media-utils
-```
-
-## Loading Audio Data
-
-Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
-
-```tsx
-import { useWindowedAudioData } from "@remotion/media-utils";
-import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-
-const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
-  src: staticFile("podcast.wav"),
-  frame,
-  fps,
-  windowInSeconds: 30,
-});
-```
-
-## Spectrum Bar Visualization
-
-Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
-
-```tsx
-import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
-import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-
-const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
-  src: staticFile("music.mp3"),
-  frame,
-  fps,
-  windowInSeconds: 30,
-});
-
-if (!audioData) {
-  return null;
-}
-
-const frequencies = visualizeAudio({
-  fps,
-  frame,
-  audioData,
-  numberOfSamples: 256,
-  optimizeFor: "speed",
-  dataOffsetInSeconds,
-});
-
-return (
-  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
-    {frequencies.map((v, i) => (
-      <div
-        key={i}
-        style={{
-          flex: 1,
-          height: `${v * 100}%`,
-          backgroundColor: "#0b84f3",
-          margin: "0 1px",
-        }}
-      />
-    ))}
-  </div>
-);
-```
-
-- `numberOfSamples` must be power of 2 (32, 64, 128, 256, 512, 1024)
-- Values range 0-1; left of array = bass, right = highs
-- Use `optimizeFor: "speed"` for Lambda or high sample counts
-
-**Important:** When passing `audioData` to child components, also pass the `frame` from the parent. Do not call `useCurrentFrame()` in each child - this causes discontinuous visualization when children are inside `<Sequence>` with offsets.
-
-## Waveform Visualization
-
-Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
-
-```tsx
-import {
-  createSmoothSvgPath,
-  useWindowedAudioData,
-  visualizeAudioWaveform,
-} from "@remotion/media-utils";
-import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-
-const frame = useCurrentFrame();
-const { width, fps } = useVideoConfig();
-const HEIGHT = 200;
-
-const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
-  src: staticFile("voice.wav"),
-  frame,
-  fps,
-  windowInSeconds: 30,
-});
-
-if (!audioData) {
-  return null;
-}
-
-const waveform = visualizeAudioWaveform({
-  fps,
-  frame,
-  audioData,
-  numberOfSamples: 256,
-  windowInSeconds: 0.5,
-  dataOffsetInSeconds,
-});
-
-const path = createSmoothSvgPath({
-  points: waveform.map((y, i) => ({
-    x: (i / (waveform.length - 1)) * width,
-    y: HEIGHT / 2 + (y * HEIGHT) / 2,
-  })),
-});
-
-return (
-  <svg width={width} height={HEIGHT}>
-    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
-  </svg>
-);
-```
-
-## Bass-Reactive Effects
-
-Extract low frequencies for beat-reactive animations:
-
-```tsx
-const frequencies = visualizeAudio({
-  fps,
-  frame,
-  audioData,
-  numberOfSamples: 128,
-  optimizeFor: "speed",
-  dataOffsetInSeconds,
-});
-
-const lowFrequencies = frequencies.slice(0, 32);
-const bassIntensity =
-  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
-
-const scale = 1 + bassIntensity * 0.5;
-const opacity = Math.min(0.6, bassIntensity * 0.8);
-```
-
-## Volume-Based Waveform
-
-Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
-
-```tsx
-import { getWaveformPortion } from "@remotion/media-utils";
-import { useCurrentFrame, useVideoConfig } from "remotion";
-
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-const currentTimeInSeconds = frame / fps;
-
-const waveform = getWaveformPortion({
-  audioData,
-  startTimeInSeconds: currentTimeInSeconds,
-  durationInSeconds: 5,
-  numberOfSamples: 50,
-});
-
-// Returns array of { index, amplitude } objects (amplitude: 0-1)
-waveform.map((bar) => (
-  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
-));
-```
-
-## Postprocessing
-
-Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
-
-```tsx
-const minDb = -100;
-const maxDb = -30;
-
-const scaled = frequencies.map((value) => {
-  const db = 20 * Math.log10(value);
-  return (db - minDb) / (maxDb - minDb);
-});
-```

.agents/skills/remotion-best-practices/rules/audio.md

@@ -1,169 +0,0 @@
----
-name: audio
-description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
-metadata:
-  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
----
-
-# Using audio in Remotion
-
-## Prerequisites
-
-First, the @remotion/media package needs to be installed.
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/media
-```
-
-## Importing Audio
-
-Use `<Audio>` from `@remotion/media` to add audio to your composition.
-
-```tsx
-import { Audio } from "@remotion/media";
-import { staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return <Audio src={staticFile("audio.mp3")} />;
-};
-```
-
-Remote URLs are also supported:
-
-```tsx
-<Audio src="https://remotion.media/audio.mp3" />
-```
-
-By default, audio plays from the start, at full volume and full length.
-Multiple audio tracks can be layered by adding multiple `<Audio>` components.
-
-## Trimming
-
-Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
-
-```tsx
-const { fps } = useVideoConfig();
-
-return (
-  <Audio
-    src={staticFile("audio.mp3")}
-    trimBefore={2 * fps} // Skip the first 2 seconds
-    trimAfter={10 * fps} // End at the 10 second mark
-  />
-);
-```
-
-The audio still starts playing at the beginning of the composition - only the specified portion is played.
-
-## Delaying
-
-Wrap the audio in a `<Sequence>` to delay when it starts:
-
-```tsx
-import { Sequence, staticFile } from "remotion";
-import { Audio } from "@remotion/media";
-
-const { fps } = useVideoConfig();
-
-return (
-  <Sequence from={1 * fps}>
-    <Audio src={staticFile("audio.mp3")} />
-  </Sequence>
-);
-```
-
-The audio will start playing after 1 second.
-
-## Volume
-
-Set a static volume (0 to 1):
-
-```tsx
-<Audio src={staticFile("audio.mp3")} volume={0.5} />
-```
-
-Or use a callback for dynamic volume based on the current frame:
-
-```tsx
-import { interpolate } from "remotion";
-
-const { fps } = useVideoConfig();
-
-return (
-  <Audio
-    src={staticFile("audio.mp3")}
-    volume={(f) =>
-      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
-    }
-  />
-);
-```
-
-The value of `f` starts at 0 when the audio begins to play, not the composition frame.
-
-## Muting
-
-Use `muted` to silence the audio. It can be set dynamically:
-
-```tsx
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-
-return (
-  <Audio
-    src={staticFile("audio.mp3")}
-    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
-  />
-);
-```
-
-## Speed
-
-Use `playbackRate` to change the playback speed:
-
-```tsx
-<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
-<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}
-```
-
-Reverse playback is not supported.
-
-## Looping
-
-Use `loop` to loop the audio indefinitely:
-
-```tsx
-<Audio src={staticFile("audio.mp3")} loop />
-```
-
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (default)
-- `"extend"`: Frame count continues incrementing
-
-```tsx
-<Audio
-  src={staticFile("audio.mp3")}
-  loop
-  loopVolumeCurveBehavior="extend"
-  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
-```
-
-## Pitch
-
-Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
-
-```tsx
-<Audio
-  src={staticFile("audio.mp3")}
-  toneFrequency={1.5} // Higher pitch
-/>
-<Audio
-  src={staticFile("audio.mp3")}
-  toneFrequency={0.8} // Lower pitch
-/>
-```
-
-Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

.agents/skills/remotion-best-practices/rules/calculate-metadata.md

@@ -1,134 +0,0 @@
----
-name: calculate-metadata
-description: Dynamically set composition duration, dimensions, and props
-metadata:
-  tags: calculateMetadata, duration, dimensions, props, dynamic
----
-
-# Using calculateMetadata
-
-Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
-
-```tsx
-<Composition
-  id="MyComp"
-  component={MyComponent}
-  durationInFrames={300}
-  fps={30}
-  width={1920}
-  height={1080}
-  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
-  calculateMetadata={calculateMetadata}
-/>
-```
-
-## Setting duration based on a video
-
-Use the [`getVideoDuration`](./get-video-duration.md) and [`getVideoDimensions`](./get-video-dimensions.md) skills to get the video duration and dimensions:
-
-```tsx
-import { CalculateMetadataFunction } from "remotion";
-import { getVideoDuration } from "./get-video-duration";
-
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  const durationInSeconds = await getVideoDuration(props.videoSrc);
-
-  return {
-    durationInFrames: Math.ceil(durationInSeconds * 30),
-  };
-};
-```
-
-## Matching dimensions of a video
-
-Use the [`getVideoDimensions`](./get-video-dimensions.md) skill to get the video dimensions:
-
-```tsx
-import { CalculateMetadataFunction } from "remotion";
-import { getVideoDuration } from "./get-video-duration";
-import { getVideoDimensions } from "./get-video-dimensions";
-
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  const dimensions = await getVideoDimensions(props.videoSrc);
-
-  return {
-    width: dimensions.width,
-    height: dimensions.height,
-  };
-};
-```
-
-## Setting duration based on multiple videos
-
-```tsx
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  const metadataPromises = props.videos.map((video) =>
-    getVideoDuration(video.src),
-  );
-  const allMetadata = await Promise.all(metadataPromises);
-
-  const totalDuration = allMetadata.reduce(
-    (sum, durationInSeconds) => sum + durationInSeconds,
-    0,
-  );
-
-  return {
-    durationInFrames: Math.ceil(totalDuration * 30),
-  };
-};
-```
-
-## Setting a default outName
-
-Set the default output filename based on props:
-
-```tsx
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  return {
-    defaultOutName: `video-${props.id}.mp4`,
-  };
-};
-```
-
-## Transforming props
-
-Fetch data or transform props before rendering:
-
-```tsx
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-  abortSignal,
-}) => {
-  const response = await fetch(props.dataUrl, { signal: abortSignal });
-  const data = await response.json();
-
-  return {
-    props: {
-      ...props,
-      fetchedData: data,
-    },
-  };
-};
-```
-
-The `abortSignal` cancels stale requests when props change in the Studio.
-
-## Return value
-
-All fields are optional. Returned values override the `<Composition>` props:
-
-- `durationInFrames`: Number of frames
-- `width`: Composition width in pixels
-- `height`: Composition height in pixels
-- `fps`: Frames per second
-- `props`: Transformed props passed to the component
-- `defaultOutName`: Default output filename
-- `defaultCodec`: Default codec for rendering

.agents/skills/remotion-best-practices/rules/can-decode.md

@@ -1,75 +0,0 @@
----
-name: can-decode
-description: Check if a video can be decoded by the browser using Mediabunny
-metadata:
-  tags: decode, validation, video, audio, compatibility, browser
----
-
-# Checking if a video can be decoded
-
-Use Mediabunny to check if a video can be decoded by the browser before attempting to play it.
-
-## The `canDecode()` function
-
-This function can be copy-pasted into any project.
-
-```tsx
-import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
-
-export const canDecode = async (src: string) => {
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(src, {
-      getRetryDelay: () => null,
-    }),
-  });
-
-  try {
-    await input.getFormat();
-  } catch {
-    return false;
-  }
-
-  const videoTrack = await input.getPrimaryVideoTrack();
-  if (videoTrack && !(await videoTrack.canDecode())) {
-    return false;
-  }
-
-  const audioTrack = await input.getPrimaryAudioTrack();
-  if (audioTrack && !(await audioTrack.canDecode())) {
-    return false;
-  }
-
-  return true;
-};
-```
-
-## Usage
-
-```tsx
-const src = "https://remotion.media/video.mp4";
-const isDecodable = await canDecode(src);
-
-if (isDecodable) {
-  console.log("Video can be decoded");
-} else {
-  console.log("Video cannot be decoded by this browser");
-}
-```
-
-## Using with Blob
-
-For file uploads or drag-and-drop, use `BlobSource`:
-
-```tsx
-import { Input, ALL_FORMATS, BlobSource } from "mediabunny";
-
-export const canDecodeBlob = async (blob: Blob) => {
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new BlobSource(blob),
-  });
-
-  // Same validation logic as above
-};
-```

.agents/skills/remotion-best-practices/rules/charts.md

@@ -1,120 +0,0 @@
----
-name: charts
-description: Chart and data visualization patterns for Remotion. Use when creating bar charts, pie charts, line charts, stock graphs, or any data-driven animations.
-metadata:
-  tags: charts, data, visualization, bar-chart, pie-chart, line-chart, stock-chart, svg-paths, graphs
----
-
-# Charts in Remotion
-
-Create charts using React code - HTML, SVG, and D3.js are all supported.
-
-Disable all animations from third party libraries - they cause flickering.  
-Drive all animations from `useCurrentFrame()`.
-
-## Bar Chart
-
-```tsx
-const STAGGER_DELAY = 5;
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-
-const bars = data.map((item, i) => {
-  const height = spring({
-    frame,
-    fps,
-    delay: i * STAGGER_DELAY,
-    config: { damping: 200 },
-  });
-  return <div style={{ height: height * item.value }} />;
-});
-```
-
-## Pie Chart
-
-Animate segments using stroke-dashoffset, starting from 12 o'clock:
-
-```tsx
-const progress = interpolate(frame, [0, 100], [0, 1]);
-const circumference = 2 * Math.PI * radius;
-const segmentLength = (value / total) * circumference;
-const offset = interpolate(progress, [0, 1], [segmentLength, 0]);
-
-<circle
-  r={radius}
-  cx={center}
-  cy={center}
-  fill="none"
-  stroke={color}
-  strokeWidth={strokeWidth}
-  strokeDasharray={`${segmentLength} ${circumference}`}
-  strokeDashoffset={offset}
-  transform={`rotate(-90 ${center} ${center})`}
-/>;
-```
-
-## Line Chart / Path Animation
-
-Use `@remotion/paths` for animating SVG paths (line charts, stock graphs, signatures).
-
-Install: `npx remotion add @remotion/paths`  
-Docs: https://remotion.dev/docs/paths.md
-
-### Convert data points to SVG path
-
-```tsx
-type Point = { x: number; y: number };
-
-const generateLinePath = (points: Point[]): string => {
-  if (points.length < 2) return "";
-  return points.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`).join(" ");
-};
-```
-
-### Draw path with animation
-
-```tsx
-import { evolvePath } from "@remotion/paths";
-
-const path = "M 100 200 L 200 150 L 300 180 L 400 100";
-const progress = interpolate(frame, [0, 2 * fps], [0, 1], {
-  extrapolateLeft: "clamp",
-  extrapolateRight: "clamp",
-  easing: Easing.out(Easing.quad),
-});
-
-const { strokeDasharray, strokeDashoffset } = evolvePath(progress, path);
-
-<path
-  d={path}
-  fill="none"
-  stroke="#FF3232"
-  strokeWidth={4}
-  strokeDasharray={strokeDasharray}
-  strokeDashoffset={strokeDashoffset}
-/>;
-```
-
-### Follow path with marker/arrow
-
-```tsx
-import {
-  getLength,
-  getPointAtLength,
-  getTangentAtLength,
-} from "@remotion/paths";
-
-const pathLength = getLength(path);
-const point = getPointAtLength(path, progress * pathLength);
-const tangent = getTangentAtLength(path, progress * pathLength);
-const angle = Math.atan2(tangent.y, tangent.x);
-
-<g
-  style={{
-    transform: `translate(${point.x}px, ${point.y}px) rotate(${angle}rad)`,
-    transformOrigin: "0 0",
-  }}
->
-  <polygon points="0,0 -20,-10 -20,10" fill="#FF3232" />
-</g>;
-```

.agents/skills/remotion-best-practices/rules/compositions.md

@@ -1,154 +0,0 @@
----
-name: compositions
-description: Defining compositions, stills, folders, default props and dynamic metadata
-metadata:
-  tags: composition, still, folder, props, metadata
----
-
-A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
-
-It normally is placed in the `src/Root.tsx` file.
-
-```tsx
-import { Composition } from "remotion";
-import { MyComposition } from "./MyComposition";
-
-export const RemotionRoot = () => {
-  return (
-    <Composition
-      id="MyComposition"
-      component={MyComposition}
-      durationInFrames={100}
-      fps={30}
-      width={1080}
-      height={1080}
-    />
-  );
-};
-```
-
-## Default Props
-
-Pass `defaultProps` to provide initial values for your component.  
-Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
-
-```tsx
-import { Composition } from "remotion";
-import { MyComposition, MyCompositionProps } from "./MyComposition";
-
-export const RemotionRoot = () => {
-  return (
-    <Composition
-      id="MyComposition"
-      component={MyComposition}
-      durationInFrames={100}
-      fps={30}
-      width={1080}
-      height={1080}
-      defaultProps={
-        {
-          title: "Hello World",
-          color: "#ff0000",
-        } satisfies MyCompositionProps
-      }
-    />
-  );
-};
-```
-
-Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
-
-## Folders
-
-Use `<Folder>` to organize compositions in the sidebar.  
-Folder names can only contain letters, numbers, and hyphens.
-
-```tsx
-import { Composition, Folder } from "remotion";
-
-export const RemotionRoot = () => {
-  return (
-    <>
-      <Folder name="Marketing">
-        <Composition id="Promo" /* ... */ />
-        <Composition id="Ad" /* ... */ />
-      </Folder>
-      <Folder name="Social">
-        <Folder name="Instagram">
-          <Composition id="Story" /* ... */ />
-          <Composition id="Reel" /* ... */ />
-        </Folder>
-      </Folder>
-    </>
-  );
-};
-```
-
-## Stills
-
-Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
-
-```tsx
-import { Still } from "remotion";
-import { Thumbnail } from "./Thumbnail";
-
-export const RemotionRoot = () => {
-  return (
-    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
-  );
-};
-```
-
-## Calculate Metadata
-
-Use `calculateMetadata` to make dimensions, duration, or props dynamic based on data.
-
-```tsx
-import { Composition, CalculateMetadataFunction } from "remotion";
-import { MyComposition, MyCompositionProps } from "./MyComposition";
-
-const calculateMetadata: CalculateMetadataFunction<
-  MyCompositionProps
-> = async ({ props, abortSignal }) => {
-  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
-    signal: abortSignal,
-  }).then((res) => res.json());
-
-  return {
-    durationInFrames: Math.ceil(data.duration * 30),
-    props: {
-      ...props,
-      videoUrl: data.url,
-    },
-  };
-};
-
-export const RemotionRoot = () => {
-  return (
-    <Composition
-      id="MyComposition"
-      component={MyComposition}
-      durationInFrames={100} // Placeholder, will be overridden
-      fps={30}
-      width={1080}
-      height={1080}
-      defaultProps={{ videoId: "abc123" }}
-      calculateMetadata={calculateMetadata}
-    />
-  );
-};
-```
-
-The function can return `props`, `durationInFrames`, `width`, `height`, `fps`, and codec-related defaults. It runs once before rendering begins.
-
-## Nesting compositions within another
-
-To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
-
-```tsx
-<AbsoluteFill>
-  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
-    <CompositionComponent />
-  </Sequence>
-</AbsoluteFill>
-```

.agents/skills/remotion-best-practices/rules/display-captions.md

@@ -1,184 +0,0 @@
----
-name: display-captions
-description: Displaying captions in Remotion with TikTok-style pages and word highlighting
-metadata:
-  tags: captions, subtitles, display, tiktok, highlight
----
-
-# Displaying captions in Remotion
-
-This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
-
-## Prerequisites
-
-Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
-
-First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/captions
-```
-
-## Fetching captions
-
-First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
-
-```tsx
-import { useState, useEffect, useCallback } from "react";
-import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
-import type { Caption } from "@remotion/captions";
-
-export const MyComponent: React.FC = () => {
-  const [captions, setCaptions] = useState<Caption[] | null>(null);
-  const { delayRender, continueRender, cancelRender } = useDelayRender();
-  const [handle] = useState(() => delayRender());
-
-  const fetchCaptions = useCallback(async () => {
-    try {
-      // Assuming captions.json is in the public/ folder.
-      const response = await fetch(staticFile("captions123.json"));
-      const data = await response.json();
-      setCaptions(data);
-      continueRender(handle);
-    } catch (e) {
-      cancelRender(e);
-    }
-  }, [continueRender, cancelRender, handle]);
-
-  useEffect(() => {
-    fetchCaptions();
-  }, [fetchCaptions]);
-
-  if (!captions) {
-    return null;
-  }
-
-  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
-};
-```
-
-## Creating pages
-
-Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
-
-```tsx
-import { useMemo } from "react";
-import { createTikTokStyleCaptions } from "@remotion/captions";
-import type { Caption } from "@remotion/captions";
-
-// How often captions should switch (in milliseconds)
-// Higher values = more words per page
-// Lower values = fewer words (more word-by-word)
-const SWITCH_CAPTIONS_EVERY_MS = 1200;
-
-const { pages } = useMemo(() => {
-  return createTikTokStyleCaptions({
-    captions,
-    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
-  });
-}, [captions]);
-```
-
-## Rendering with Sequences
-
-Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
-
-```tsx
-import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
-import type { TikTokPage } from "@remotion/captions";
-
-const CaptionedContent: React.FC = () => {
-  const { fps } = useVideoConfig();
-
-  return (
-    <AbsoluteFill>
-      {pages.map((page, index) => {
-        const nextPage = pages[index + 1] ?? null;
-        const startFrame = (page.startMs / 1000) * fps;
-        const endFrame = Math.min(
-          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
-          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
-        );
-        const durationInFrames = endFrame - startFrame;
-
-        if (durationInFrames <= 0) {
-          return null;
-        }
-
-        return (
-          <Sequence
-            key={index}
-            from={startFrame}
-            durationInFrames={durationInFrames}
-          >
-            <CaptionPage page={page} />
-          </Sequence>
-        );
-      })}
-    </AbsoluteFill>
-  );
-};
-```
-
-## White-space preservation
-
-The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
-
-## Separate component for captions
-
-Put captioning logic in a separate component.  
-Make a new file for it.
-
-## Word highlighting
-
-A caption page contains `tokens` which you can use to highlight the currently spoken word:
-
-```tsx
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
-import type { TikTokPage } from "@remotion/captions";
-
-const HIGHLIGHT_COLOR = "#39E508";
-
-const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-
-  // Current time relative to the start of the sequence
-  const currentTimeMs = (frame / fps) * 1000;
-  // Convert to absolute time by adding the page start
-  const absoluteTimeMs = page.startMs + currentTimeMs;
-
-  return (
-    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
-      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
-        {page.tokens.map((token) => {
-          const isActive =
-            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
-
-          return (
-            <span
-              key={token.fromMs}
-              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
-            >
-              {token.text}
-            </span>
-          );
-        })}
-      </div>
-    </AbsoluteFill>
-  );
-};
-```
-
-## Display captions alongside video content
-
-By default, put the captions alongside the video content, so the captions are in sync.  
-For each video, make a new captions JSON file.
-
-```tsx
-<AbsoluteFill>
-  <Video src={staticFile("video.mp4")} />
-  <CaptionPage page={page} />
-</AbsoluteFill>
-```

.agents/skills/remotion-best-practices/rules/extract-frames.md

@@ -1,229 +0,0 @@
----
-name: extract-frames
-description: Extract frames from videos at specific timestamps using Mediabunny
-metadata:
-  tags: frames, extract, video, thumbnail, filmstrip, canvas
----
-
-# Extracting frames from videos
-
-Use Mediabunny to extract frames from videos at specific timestamps. This is useful for generating thumbnails, filmstrips, or processing individual frames.
-
-## The `extractFrames()` function
-
-This function can be copy-pasted into any project.
-
-```tsx
-import {
-  ALL_FORMATS,
-  Input,
-  UrlSource,
-  VideoSample,
-  VideoSampleSink,
-} from "mediabunny";
-
-type Options = {
-  track: { width: number; height: number };
-  container: string;
-  durationInSeconds: number | null;
-};
-
-export type ExtractFramesTimestampsInSecondsFn = (
-  options: Options,
-) => Promise<number[]> | number[];
-
-export type ExtractFramesProps = {
-  src: string;
-  timestampsInSeconds: number[] | ExtractFramesTimestampsInSecondsFn;
-  onVideoSample: (sample: VideoSample) => void;
-  signal?: AbortSignal;
-};
-
-export async function extractFrames({
-  src,
-  timestampsInSeconds,
-  onVideoSample,
-  signal,
-}: ExtractFramesProps): Promise<void> {
-  using input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(src),
-  });
-
-  const [durationInSeconds, format, videoTrack] = await Promise.all([
-    input.computeDuration(),
-    input.getFormat(),
-    input.getPrimaryVideoTrack(),
-  ]);
-
-  if (!videoTrack) {
-    throw new Error("No video track found in the input");
-  }
-
-  if (signal?.aborted) {
-    throw new Error("Aborted");
-  }
-
-  const timestamps =
-    typeof timestampsInSeconds === "function"
-      ? await timestampsInSeconds({
-          track: {
-            width: videoTrack.displayWidth,
-            height: videoTrack.displayHeight,
-          },
-          container: format.name,
-          durationInSeconds,
-        })
-      : timestampsInSeconds;
-
-  if (timestamps.length === 0) {
-    return;
-  }
-
-  if (signal?.aborted) {
-    throw new Error("Aborted");
-  }
-
-  const sink = new VideoSampleSink(videoTrack);
-
-  for await (using videoSample of sink.samplesAtTimestamps(timestamps)) {
-    if (signal?.aborted) {
-      break;
-    }
-
-    if (!videoSample) {
-      continue;
-    }
-
-    onVideoSample(videoSample);
-  }
-}
-```
-
-## Basic usage
-
-Extract frames at specific timestamps:
-
-```tsx
-await extractFrames({
-  src: "https://remotion.media/video.mp4",
-  timestampsInSeconds: [0, 1, 2, 3, 4],
-  onVideoSample: (sample) => {
-    const canvas = document.createElement("canvas");
-    canvas.width = sample.displayWidth;
-    canvas.height = sample.displayHeight;
-    const ctx = canvas.getContext("2d");
-    sample.draw(ctx!, 0, 0);
-  },
-});
-```
-
-## Creating a filmstrip
-
-Use a callback function to dynamically calculate timestamps based on video metadata:
-
-```tsx
-const canvasWidth = 500;
-const canvasHeight = 80;
-const fromSeconds = 0;
-const toSeconds = 10;
-
-await extractFrames({
-  src: "https://remotion.media/video.mp4",
-  timestampsInSeconds: async ({ track, durationInSeconds }) => {
-    const aspectRatio = track.width / track.height;
-    const amountOfFramesFit = Math.ceil(
-      canvasWidth / (canvasHeight * aspectRatio),
-    );
-    const segmentDuration = toSeconds - fromSeconds;
-    const timestamps: number[] = [];
-
-    for (let i = 0; i < amountOfFramesFit; i++) {
-      timestamps.push(
-        fromSeconds + (segmentDuration / amountOfFramesFit) * (i + 0.5),
-      );
-    }
-
-    return timestamps;
-  },
-  onVideoSample: (sample) => {
-    console.log(`Frame at ${sample.timestamp}s`);
-
-    const canvas = document.createElement("canvas");
-    canvas.width = sample.displayWidth;
-    canvas.height = sample.displayHeight;
-    const ctx = canvas.getContext("2d");
-    sample.draw(ctx!, 0, 0);
-  },
-});
-```
-
-## Cancellation with AbortSignal
-
-Cancel frame extraction after a timeout:
-
-```tsx
-const controller = new AbortController();
-
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  await extractFrames({
-    src: "https://remotion.media/video.mp4",
-    timestampsInSeconds: [0, 1, 2, 3, 4],
-    onVideoSample: (sample) => {
-      using frame = sample;
-      const canvas = document.createElement("canvas");
-      canvas.width = frame.displayWidth;
-      canvas.height = frame.displayHeight;
-      const ctx = canvas.getContext("2d");
-      frame.draw(ctx!, 0, 0);
-    },
-    signal: controller.signal,
-  });
-
-  console.log("Frame extraction complete!");
-} catch (error) {
-  console.error("Frame extraction was aborted or failed:", error);
-}
-```
-
-## Timeout with Promise.race
-
-```tsx
-const controller = new AbortController();
-
-const timeoutPromise = new Promise<never>((_, reject) => {
-  const timeoutId = setTimeout(() => {
-    controller.abort();
-    reject(new Error("Frame extraction timed out after 10 seconds"));
-  }, 10000);
-
-  controller.signal.addEventListener("abort", () => clearTimeout(timeoutId), {
-    once: true,
-  });
-});
-
-try {
-  await Promise.race([
-    extractFrames({
-      src: "https://remotion.media/video.mp4",
-      timestampsInSeconds: [0, 1, 2, 3, 4],
-      onVideoSample: (sample) => {
-        using frame = sample;
-        const canvas = document.createElement("canvas");
-        canvas.width = frame.displayWidth;
-        canvas.height = frame.displayHeight;
-        const ctx = canvas.getContext("2d");
-        frame.draw(ctx!, 0, 0);
-      },
-      signal: controller.signal,
-    }),
-    timeoutPromise,
-  ]);
-
-  console.log("Frame extraction complete!");
-} catch (error) {
-  console.error("Frame extraction was aborted or failed:", error);
-}
-```

.agents/skills/remotion-best-practices/rules/ffmpeg.md

@@ -1,38 +0,0 @@
----
-name: ffmpeg
-description: Using FFmpeg and FFprobe in Remotion
-metadata:
-  tags: ffmpeg, ffprobe, video, trimming
----
-
-## FFmpeg in Remotion
-
-`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `bunx remotion ffmpeg` and `bunx remotion ffprobe`:
-
-```bash
-bunx remotion ffmpeg -i input.mp4 output.mp3
-bunx remotion ffprobe input.mp4
-```
-
-### Trimming videos
-
-You have 2 options for trimming videos:
-
-1. Use the FFMpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video.
-
-```bash
-# Re-encodes from the exact frame
-bunx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
-```
-
-2. Use the `trimBefore` and `trimAfter` props of the `<Video>` component. The benefit is that this is non-destructive and you can change the trim at any time.
-
-```tsx
-import { Video } from "@remotion/media";
-
-<Video
-  src={staticFile("video.mp4")}
-  trimBefore={5 * fps}
-  trimAfter={10 * fps}
-/>;
-```

.agents/skills/remotion-best-practices/rules/fonts.md

@@ -1,152 +0,0 @@
----
-name: fonts
-description: Loading Google Fonts and local fonts in Remotion
-metadata:
-  tags: fonts, google-fonts, typography, text
----
-
-# Using fonts in Remotion
-
-## Google Fonts with @remotion/google-fonts
-
-The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
-
-### Prerequisites
-
-First, the @remotion/google-fonts package needs to be installed.
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/google-fonts # If project uses npm
-bunx remotion add @remotion/google-fonts # If project uses bun
-yarn remotion add @remotion/google-fonts # If project uses yarn
-pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
-```
-
-```tsx
-import { loadFont } from "@remotion/google-fonts/Lobster";
-
-const { fontFamily } = loadFont();
-
-export const MyComposition = () => {
-  return <div style={{ fontFamily }}>Hello World</div>;
-};
-```
-
-Preferrably, specify only needed weights and subsets to reduce file size:
-
-```tsx
-import { loadFont } from "@remotion/google-fonts/Roboto";
-
-const { fontFamily } = loadFont("normal", {
-  weights: ["400", "700"],
-  subsets: ["latin"],
-});
-```
-
-### Waiting for font to load
-
-Use `waitUntilDone()` if you need to know when the font is ready:
-
-```tsx
-import { loadFont } from "@remotion/google-fonts/Lobster";
-
-const { fontFamily, waitUntilDone } = loadFont();
-
-await waitUntilDone();
-```
-
-## Local fonts with @remotion/fonts
-
-For local font files, use the `@remotion/fonts` package.
-
-### Prerequisites
-
-First, install @remotion/fonts:
-
-```bash
-npx remotion add @remotion/fonts # If project uses npm
-bunx remotion add @remotion/fonts # If project uses bun
-yarn remotion add @remotion/fonts # If project uses yarn
-pnpm exec remotion add @remotion/fonts # If project uses pnpm
-```
-
-### Loading a local font
-
-Place your font file in the `public/` folder and use `loadFont()`:
-
-```tsx
-import { loadFont } from "@remotion/fonts";
-import { staticFile } from "remotion";
-
-await loadFont({
-  family: "MyFont",
-  url: staticFile("MyFont-Regular.woff2"),
-});
-
-export const MyComposition = () => {
-  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
-};
-```
-
-### Loading multiple weights
-
-Load each weight separately with the same family name:
-
-```tsx
-import { loadFont } from "@remotion/fonts";
-import { staticFile } from "remotion";
-
-await Promise.all([
-  loadFont({
-    family: "Inter",
-    url: staticFile("Inter-Regular.woff2"),
-    weight: "400",
-  }),
-  loadFont({
-    family: "Inter",
-    url: staticFile("Inter-Bold.woff2"),
-    weight: "700",
-  }),
-]);
-```
-
-### Available options
-
-```tsx
-loadFont({
-  family: "MyFont", // Required: name to use in CSS
-  url: staticFile("font.woff2"), // Required: font file URL
-  format: "woff2", // Optional: auto-detected from extension
-  weight: "400", // Optional: font weight
-  style: "normal", // Optional: normal or italic
-  display: "block", // Optional: font-display behavior
-});
-```
-
-## Using in components
-
-Call `loadFont()` at the top level of your component or in a separate file that's imported early:
-
-```tsx
-import { loadFont } from "@remotion/google-fonts/Montserrat";
-
-const { fontFamily } = loadFont("normal", {
-  weights: ["400", "700"],
-  subsets: ["latin"],
-});
-
-export const Title: React.FC<{ text: string }> = ({ text }) => {
-  return (
-    <h1
-      style={{
-        fontFamily,
-        fontSize: 80,
-        fontWeight: "bold",
-      }}
-    >
-      {text}
-    </h1>
-  );
-};
-```

.agents/skills/remotion-best-practices/rules/get-audio-duration.md

@@ -1,58 +0,0 @@
----
-name: get-audio-duration
-description: Getting the duration of an audio file in seconds with Mediabunny
-metadata:
-  tags: duration, audio, length, time, seconds, mp3, wav
----
-
-# Getting audio duration with Mediabunny
-
-Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
-
-## Getting audio duration
-
-```tsx title="get-audio-duration.ts"
-import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
-
-export const getAudioDuration = async (src: string) => {
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(src, {
-      getRetryDelay: () => null,
-    }),
-  });
-
-  const durationInSeconds = await input.computeDuration();
-  return durationInSeconds;
-};
-```
-
-## Usage
-
-```tsx
-const duration = await getAudioDuration("https://remotion.media/audio.mp3");
-console.log(duration); // e.g. 180.5 (seconds)
-```
-
-## Using with staticFile in Remotion
-
-Make sure to wrap the file path in `staticFile()`:
-
-```tsx
-import { staticFile } from "remotion";
-
-const duration = await getAudioDuration(staticFile("audio.mp3"));
-```
-
-## In Node.js and Bun
-
-Use `FileSource` instead of `UrlSource`:
-
-```tsx
-import { Input, ALL_FORMATS, FileSource } from "mediabunny";
-
-const input = new Input({
-  formats: ALL_FORMATS,
-  source: new FileSource(file), // File object from input or drag-drop
-});
-```

.agents/skills/remotion-best-practices/rules/get-video-dimensions.md

@@ -1,68 +0,0 @@
----
-name: get-video-dimensions
-description: Getting the width and height of a video file with Mediabunny
-metadata:
-  tags: dimensions, width, height, resolution, size, video
----
-
-# Getting video dimensions with Mediabunny
-
-Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
-
-## Getting video dimensions
-
-```tsx
-import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
-
-export const getVideoDimensions = async (src: string) => {
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(src, {
-      getRetryDelay: () => null,
-    }),
-  });
-
-  const videoTrack = await input.getPrimaryVideoTrack();
-  if (!videoTrack) {
-    throw new Error("No video track found");
-  }
-
-  return {
-    width: videoTrack.displayWidth,
-    height: videoTrack.displayHeight,
-  };
-};
-```
-
-## Usage
-
-```tsx
-const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
-console.log(dimensions.width); // e.g. 1920
-console.log(dimensions.height); // e.g. 1080
-```
-
-## Using with local files
-
-For local files, use `FileSource` instead of `UrlSource`:
-
-```tsx
-import { Input, ALL_FORMATS, FileSource } from "mediabunny";
-
-const input = new Input({
-  formats: ALL_FORMATS,
-  source: new FileSource(file), // File object from input or drag-drop
-});
-
-const videoTrack = await input.getPrimaryVideoTrack();
-const width = videoTrack.displayWidth;
-const height = videoTrack.displayHeight;
-```
-
-## Using with staticFile in Remotion
-
-```tsx
-import { staticFile } from "remotion";
-
-const dimensions = await getVideoDimensions(staticFile("video.mp4"));
-```

.agents/skills/remotion-best-practices/rules/get-video-duration.md

@@ -1,60 +0,0 @@
----
-name: get-video-duration
-description: Getting the duration of a video file in seconds with Mediabunny
-metadata:
-  tags: duration, video, length, time, seconds
----
-
-# Getting video duration with Mediabunny
-
-Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
-
-## Getting video duration
-
-```tsx
-import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
-
-export const getVideoDuration = async (src: string) => {
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(src, {
-      getRetryDelay: () => null,
-    }),
-  });
-
-  const durationInSeconds = await input.computeDuration();
-  return durationInSeconds;
-};
-```
-
-## Usage
-
-```tsx
-const duration = await getVideoDuration("https://remotion.media/video.mp4");
-console.log(duration); // e.g. 10.5 (seconds)
-```
-
-## Video files from the public/ directory
-
-Make sure to wrap the file path in `staticFile()`:
-
-```tsx
-import { staticFile } from "remotion";
-
-const duration = await getVideoDuration(staticFile("video.mp4"));
-```
-
-## In Node.js and Bun
-
-Use `FileSource` instead of `UrlSource`:
-
-```tsx
-import { Input, ALL_FORMATS, FileSource } from "mediabunny";
-
-const input = new Input({
-  formats: ALL_FORMATS,
-  source: new FileSource(file), // File object from input or drag-drop
-});
-
-const durationInSeconds = await input.computeDuration();
-```

.agents/skills/remotion-best-practices/rules/gifs.md

@@ -1,141 +0,0 @@
----
-name: gif
-description: Displaying GIFs, APNG, AVIF and WebP in Remotion
-metadata:
-  tags: gif, animation, images, animated, apng, avif, webp
----
-
-# Using Animated images in Remotion
-
-## Basic usage
-
-Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
-
-```tsx
-import { AnimatedImage, staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return (
-    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
-  );
-};
-```
-
-Remote URLs are also supported (must have CORS enabled):
-
-```tsx
-<AnimatedImage
-  src="https://example.com/animation.gif"
-  width={500}
-  height={500}
-/>
-```
-
-## Sizing and fit
-
-Control how the image fills its container with the `fit` prop:
-
-```tsx
-// Stretch to fill (default)
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />
-
-// Maintain aspect ratio, fit inside container
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />
-
-// Fill container, crop if needed
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />
-```
-
-## Playback speed
-
-Use `playbackRate` to control the animation speed:
-
-```tsx
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}
-```
-
-## Looping behavior
-
-Control what happens when the animation finishes:
-
-```tsx
-// Loop indefinitely (default)
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />
-
-// Play once, show final frame
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />
-
-// Play once, then clear canvas
-<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />
-```
-
-## Styling
-
-Use the `style` prop for additional CSS (use `width` and `height` props for sizing):
-
-```tsx
-<AnimatedImage
-  src={staticFile("animation.gif")}
-  width={500}
-  height={500}
-  style={{
-    borderRadius: 20,
-    position: "absolute",
-    top: 100,
-    left: 50,
-  }}
-/>
-```
-
-## Getting GIF duration
-
-Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
-
-```bash
-npx remotion add @remotion/gif
-```
-
-```tsx
-import { getGifDurationInSeconds } from "@remotion/gif";
-import { staticFile } from "remotion";
-
-const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
-console.log(duration); // e.g. 2.5
-```
-
-This is useful for setting the composition duration to match the GIF:
-
-```tsx
-import { getGifDurationInSeconds } from "@remotion/gif";
-import { staticFile, CalculateMetadataFunction } from "remotion";
-
-const calculateMetadata: CalculateMetadataFunction = async () => {
-  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
-  return {
-    durationInFrames: Math.ceil(duration * 30),
-  };
-};
-```
-
-## Alternative
-
-If `<AnimatedImage>` does not work (only supported in Chrome and Firefox), you can use `<Gif>` from `@remotion/gif` instead.
-
-```bash
-npx remotion add @remotion/gif # If project uses npm
-bunx remotion add @remotion/gif # If project uses bun
-yarn remotion add @remotion/gif # If project uses yarn
-pnpm exec remotion add @remotion/gif # If project uses pnpm
-```
-
-```tsx
-import { Gif } from "@remotion/gif";
-import { staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
-};
-```
-
-The `<Gif>` component has the same props as `<AnimatedImage>` but only supports GIF files.

.agents/skills/remotion-best-practices/rules/images.md

@@ -1,134 +0,0 @@
----
-name: images
-description: Embedding images in Remotion using the <Img> component
-metadata:
-  tags: images, img, staticFile, png, jpg, svg, webp
----
-
-# Using images in Remotion
-
-## The `<Img>` component
-
-Always use the `<Img>` component from `remotion` to display images:
-
-```tsx
-import { Img, staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return <Img src={staticFile("photo.png")} />;
-};
-```
-
-## Important restrictions
-
-**You MUST use the `<Img>` component from `remotion`.** Do not use:
-
-- Native HTML `<img>` elements
-- Next.js `<Image>` component
-- CSS `background-image`
-
-The `<Img>` component ensures images are fully loaded before rendering, preventing flickering and blank frames during video export.
-
-## Local images with staticFile()
-
-Place images in the `public/` folder and use `staticFile()` to reference them:
-
-```
-my-video/
-├─ public/
-│  ├─ logo.png
-│  ├─ avatar.jpg
-│  └─ icon.svg
-├─ src/
-├─ package.json
-```
-
-```tsx
-import { Img, staticFile } from "remotion";
-
-<Img src={staticFile("logo.png")} />;
-```
-
-## Remote images
-
-Remote URLs can be used directly without `staticFile()`:
-
-```tsx
-<Img src="https://example.com/image.png" />
-```
-
-Ensure remote images have CORS enabled.
-
-For animated GIFs, use the `<Gif>` component from `@remotion/gif` instead.
-
-## Sizing and positioning
-
-Use the `style` prop to control size and position:
-
-```tsx
-<Img
-  src={staticFile("photo.png")}
-  style={{
-    width: 500,
-    height: 300,
-    position: "absolute",
-    top: 100,
-    left: 50,
-    objectFit: "cover",
-  }}
-/>
-```
-
-## Dynamic image paths
-
-Use template literals for dynamic file references:
-
-```tsx
-import { Img, staticFile, useCurrentFrame } from "remotion";
-
-const frame = useCurrentFrame();
-
-// Image sequence
-<Img src={staticFile(`frames/frame${frame}.png`)} />
-
-// Selecting based on props
-<Img src={staticFile(`avatars/${props.userId}.png`)} />
-
-// Conditional images
-<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />
-```
-
-This pattern is useful for:
-
-- Image sequences (frame-by-frame animations)
-- User-specific avatars or profile images
-- Theme-based icons
-- State-dependent graphics
-
-## Getting image dimensions
-
-Use `getImageDimensions()` to get the dimensions of an image:
-
-```tsx
-import { getImageDimensions, staticFile } from "remotion";
-
-const { width, height } = await getImageDimensions(staticFile("photo.png"));
-```
-
-This is useful for calculating aspect ratios or sizing compositions:
-
-```tsx
-import {
-  getImageDimensions,
-  staticFile,
-  CalculateMetadataFunction,
-} from "remotion";
-
-const calculateMetadata: CalculateMetadataFunction = async () => {
-  const { width, height } = await getImageDimensions(staticFile("photo.png"));
-  return {
-    width,
-    height,
-  };
-};
-```

.agents/skills/remotion-best-practices/rules/import-srt-captions.md

@@ -1,69 +0,0 @@
----
-name: import-srt-captions
-description: Importing .srt subtitle files into Remotion using @remotion/captions
-metadata:
-  tags: captions, subtitles, srt, import, parse
----
-
-# Importing .srt subtitles into Remotion
-
-If you have an existing `.srt` subtitle file, you can import it into Remotion using `parseSrt()` from `@remotion/captions`.
-
-If you don't have a .srt file, read [Transcribing audio](transcribe-captions.md) for how to generate captions instead.
-
-## Prerequisites
-
-First, the @remotion/captions package needs to be installed.
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/captions # If project uses npm
-bunx remotion add @remotion/captions # If project uses bun
-yarn remotion add @remotion/captions # If project uses yarn
-pnpm exec remotion add @remotion/captions # If project uses pnpm
-```
-
-## Reading an .srt file
-
-Use `staticFile()` to reference an `.srt` file in your `public` folder, then fetch and parse it:
-
-```tsx
-import { useState, useEffect, useCallback } from "react";
-import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
-import { parseSrt } from "@remotion/captions";
-import type { Caption } from "@remotion/captions";
-
-export const MyComponent: React.FC = () => {
-  const [captions, setCaptions] = useState<Caption[] | null>(null);
-  const { delayRender, continueRender, cancelRender } = useDelayRender();
-  const [handle] = useState(() => delayRender());
-
-  const fetchCaptions = useCallback(async () => {
-    try {
-      const response = await fetch(staticFile("subtitles.srt"));
-      const text = await response.text();
-      const { captions: parsed } = parseSrt({ input: text });
-      setCaptions(parsed);
-      continueRender(handle);
-    } catch (e) {
-      cancelRender(e);
-    }
-  }, [continueRender, cancelRender, handle]);
-
-  useEffect(() => {
-    fetchCaptions();
-  }, [fetchCaptions]);
-
-  if (!captions) {
-    return null;
-  }
-
-  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
-};
-```
-
-Remote URLs are also supported - you can `fetch()` a remote file via URL instead of using `staticFile()`.
-
-## Using imported captions
-
-Once parsed, the captions are in the `Caption` format and can be used with all `@remotion/captions` utilities.

.agents/skills/remotion-best-practices/rules/light-leaks.md

@@ -1,73 +0,0 @@
----
-name: light-leaks
-description: Light leak overlay effects for Remotion using @remotion/light-leaks.
-metadata:
-  tags: light-leaks, overlays, effects, transitions
----
-
-## Light Leaks
-
-This only works from Remotion 4.0.415 and up. Use `npx remotion versions` to check your Remotion version and `npx remotion upgrade` to upgrade your Remotion version.
-
-`<LightLeak>` from `@remotion/light-leaks` renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.
-
-Typically used inside a `<TransitionSeries.Overlay>` to play over the cut point between two scenes. See the **transitions** rule for `<TransitionSeries>` and overlay usage.
-
-## Prerequisites
-
-```bash
-npx remotion add @remotion/light-leaks
-```
-
-## Basic usage with TransitionSeries
-
-```tsx
-import { TransitionSeries } from "@remotion/transitions";
-import { LightLeak } from "@remotion/light-leaks";
-
-<TransitionSeries>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneA />
-  </TransitionSeries.Sequence>
-  <TransitionSeries.Overlay durationInFrames={30}>
-    <LightLeak />
-  </TransitionSeries.Overlay>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneB />
-  </TransitionSeries.Sequence>
-</TransitionSeries>;
-```
-
-## Props
-
-- `durationInFrames?` — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
-- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
-- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
-
-## Customizing the look
-
-```tsx
-import { LightLeak } from "@remotion/light-leaks";
-
-// Blue-tinted light leak with a different pattern
-<LightLeak seed={5} hueShift={240} />;
-
-// Green-tinted light leak
-<LightLeak seed={2} hueShift={120} />;
-```
-
-## Standalone usage
-
-`<LightLeak>` can also be used outside of `<TransitionSeries>`, for example as a decorative overlay in any composition:
-
-```tsx
-import { AbsoluteFill } from "remotion";
-import { LightLeak } from "@remotion/light-leaks";
-
-const MyComp: React.FC = () => (
-  <AbsoluteFill>
-    <MyContent />
-    <LightLeak durationInFrames={60} seed={3} />
-  </AbsoluteFill>
-);
-```

.agents/skills/remotion-best-practices/rules/lottie.md

@@ -1,70 +0,0 @@
----
-name: lottie
-description: Embedding Lottie animations in Remotion.
-metadata:
-  category: Animation
----
-
-# Using Lottie Animations in Remotion
-
-## Prerequisites
-
-First, the @remotion/lottie package needs to be installed.  
-If it is not, use the following command:
-
-```bash
-npx remotion add @remotion/lottie # If project uses npm
-bunx remotion add @remotion/lottie # If project uses bun
-yarn remotion add @remotion/lottie # If project uses yarn
-pnpm exec remotion add @remotion/lottie # If project uses pnpm
-```
-
-## Displaying a Lottie file
-
-To import a Lottie animation:
-
-- Fetch the Lottie asset
-- Wrap the loading process in `delayRender()` and `continueRender()`
-- Save the animation data in a state
-- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
-
-```tsx
-import { Lottie, LottieAnimationData } from "@remotion/lottie";
-import { useEffect, useState } from "react";
-import { cancelRender, continueRender, delayRender } from "remotion";
-
-export const MyAnimation = () => {
-  const [handle] = useState(() => delayRender("Loading Lottie animation"));
-
-  const [animationData, setAnimationData] =
-    useState<LottieAnimationData | null>(null);
-
-  useEffect(() => {
-    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
-      .then((data) => data.json())
-      .then((json) => {
-        setAnimationData(json);
-        continueRender(handle);
-      })
-      .catch((err) => {
-        cancelRender(err);
-      });
-  }, [handle]);
-
-  if (!animationData) {
-    return null;
-  }
-
-  return <Lottie animationData={animationData} />;
-};
-```
-
-## Styling and animating
-
-Lottie supports the `style` prop to allow styles and animations:
-
-```tsx
-return (
-  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
-);
-```

.agents/skills/remotion-best-practices/rules/maps.md

@@ -1,412 +0,0 @@
----
-name: maps
-description: Make map animations with Mapbox
-metadata:
-  tags: map, map animation, mapbox
----
-
-Maps can be added to a Remotion video with Mapbox.  
-The [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/api/) has the API reference.
-
-## Prerequisites
-
-Mapbox and `@turf/turf` need to be installed.
-
-Search the project for lockfiles and run the correct command depending on the package manager:
-
-If `package-lock.json` is found, use the following command:
-
-```bash
-npm i mapbox-gl @turf/turf @types/mapbox-gl
-```
-
-If `bun.lock` is found, use the following command:
-
-```bash
-bun i mapbox-gl @turf/turf @types/mapbox-gl
-```
-
-If `yarn.lock` is found, use the following command:
-
-```bash
-yarn add mapbox-gl @turf/turf @types/mapbox-gl
-```
-
-If `pnpm-lock.yaml` is found, use the following command:
-
-```bash
-pnpm i mapbox-gl @turf/turf @types/mapbox-gl
-```
-
-The user needs to create a free Mapbox account and create an access token by visiting https://console.mapbox.com/account/access-tokens/.
-
-The mapbox token needs to be added to the `.env` file:
-
-```txt title=".env"
-REMOTION_MAPBOX_TOKEN==pk.your-mapbox-access-token
-```
-
-## Adding a map
-
-Here is a basic example of a map in Remotion.
-
-```tsx
-import { useEffect, useMemo, useRef, useState } from "react";
-import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
-import mapboxgl, { Map } from "mapbox-gl";
-
-export const lineCoordinates = [
-  [6.56158447265625, 46.059891147620725],
-  [6.5691375732421875, 46.05679376154153],
-  [6.5842437744140625, 46.05059898938315],
-  [6.594886779785156, 46.04702502069337],
-  [6.601066589355469, 46.0460718554722],
-  [6.6089630126953125, 46.0365370783104],
-  [6.6185760498046875, 46.018420689207964],
-];
-
-mapboxgl.accessToken = process.env.REMOTION_MAPBOX_TOKEN as string;
-
-export const MyComposition = () => {
-  const ref = useRef<HTMLDivElement>(null);
-  const { delayRender, continueRender } = useDelayRender();
-
-  const { width, height } = useVideoConfig();
-  const [handle] = useState(() => delayRender("Loading map..."));
-  const [map, setMap] = useState<Map | null>(null);
-
-  useEffect(() => {
-    const _map = new Map({
-      container: ref.current!,
-      zoom: 11.53,
-      center: [6.5615, 46.0598],
-      pitch: 65,
-      bearing: 0,
-      style: "⁠mapbox://styles/mapbox/standard",
-      interactive: false,
-      fadeDuration: 0,
-    });
-
-    _map.on("style.load", () => {
-      // Hide all features from the Mapbox Standard style
-      const hideFeatures = [
-        "showRoadsAndTransit",
-        "showRoads",
-        "showTransit",
-        "showPedestrianRoads",
-        "showRoadLabels",
-        "showTransitLabels",
-        "showPlaceLabels",
-        "showPointOfInterestLabels",
-        "showPointsOfInterest",
-        "showAdminBoundaries",
-        "showLandmarkIcons",
-        "showLandmarkIconLabels",
-        "show3dObjects",
-        "show3dBuildings",
-        "show3dTrees",
-        "show3dLandmarks",
-        "show3dFacades",
-      ];
-      for (const feature of hideFeatures) {
-        _map.setConfigProperty("basemap", feature, false);
-      }
-
-      _map.setConfigProperty("basemap", "colorTrunks", "rgba(0, 0, 0, 0)");
-
-      _map.addSource("trace", {
-        type: "geojson",
-        data: {
-          type: "Feature",
-          properties: {},
-          geometry: {
-            type: "LineString",
-            coordinates: lineCoordinates,
-          },
-        },
-      });
-      _map.addLayer({
-        type: "line",
-        source: "trace",
-        id: "line",
-        paint: {
-          "line-color": "black",
-          "line-width": 5,
-        },
-        layout: {
-          "line-cap": "round",
-          "line-join": "round",
-        },
-      });
-    });
-
-    _map.on("load", () => {
-      continueRender(handle);
-      setMap(_map);
-    });
-  }, [handle, lineCoordinates]);
-
-  const style: React.CSSProperties = useMemo(
-    () => ({ width, height, position: "absolute" }),
-    [width, height],
-  );
-
-  return <AbsoluteFill ref={ref} style={style} />;
-};
-```
-
-The following is important in Remotion:
-
-- Animations must be driven by `useCurrentFrame()` and animations that Mapbox brings itself should be disabled. For example, the `fadeDuration` prop should be set to `0`, `interactive` should be set to `false`, etc.
-- Loading the map should be delayed using `useDelayRender()` and the map should be set to `null` until it is loaded.
-- The element containing the ref MUST have an explicit width and height and `position: "absolute"`.
-- Do not add a `_map.remove();` cleanup function.
-
-## Drawing lines
-
-Unless I request it, do not add a glow effect to the lines.
-Unless I request it, do not add additional points to the lines.
-
-## Map style
-
-By default, use the `mapbox://styles/mapbox/standard` style.  
-Hide the labels from the base map style.
-
-Unless I request otherwise, remove all features from the Mapbox Standard style.
-
-```tsx
-// Hide all features from the Mapbox Standard style
-const hideFeatures = [
-  "showRoadsAndTransit",
-  "showRoads",
-  "showTransit",
-  "showPedestrianRoads",
-  "showRoadLabels",
-  "showTransitLabels",
-  "showPlaceLabels",
-  "showPointOfInterestLabels",
-  "showPointsOfInterest",
-  "showAdminBoundaries",
-  "showLandmarkIcons",
-  "showLandmarkIconLabels",
-  "show3dObjects",
-  "show3dBuildings",
-  "show3dTrees",
-  "show3dLandmarks",
-  "show3dFacades",
-];
-for (const feature of hideFeatures) {
-  _map.setConfigProperty("basemap", feature, false);
-}
-
-_map.setConfigProperty("basemap", "colorMotorways", "transparent");
-_map.setConfigProperty("basemap", "colorRoads", "transparent");
-_map.setConfigProperty("basemap", "colorTrunks", "transparent");
-```
-
-## Animating the camera
-
-You can animate the camera along the line by adding a `useEffect` hook that updates the camera position based on the current frame.
-
-Unless I ask for it, do not jump between camera angles.
-
-```tsx
-import * as turf from "@turf/turf";
-import { interpolate } from "remotion";
-import { Easing } from "remotion";
-import { useCurrentFrame, useVideoConfig, useDelayRender } from "remotion";
-
-const animationDuration = 20;
-const cameraAltitude = 4000;
-```
-
-```tsx
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-const { delayRender, continueRender } = useDelayRender();
-
-useEffect(() => {
-  if (!map) {
-    return;
-  }
-  const handle = delayRender("Moving point...");
-
-  const routeDistance = turf.length(turf.lineString(lineCoordinates));
-
-  const progress = interpolate(
-    frame / fps,
-    [0.00001, animationDuration],
-    [0, 1],
-    {
-      easing: Easing.inOut(Easing.sin),
-      extrapolateLeft: "clamp",
-      extrapolateRight: "clamp",
-    },
-  );
-
-  const camera = map.getFreeCameraOptions();
-
-  const alongRoute = turf.along(
-    turf.lineString(lineCoordinates),
-    routeDistance * progress,
-  ).geometry.coordinates;
-
-  camera.lookAtPoint({
-    lng: alongRoute[0],
-    lat: alongRoute[1],
-  });
-
-  map.setFreeCameraOptions(camera);
-  map.once("idle", () => continueRender(handle));
-}, [lineCoordinates, fps, frame, handle, map]);
-```
-
-Notes:
-
-IMPORTANT: Keep the camera by default so north is up.
-IMPORTANT: For multi-step animations, set all properties at all stages (zoom, position, line progress) to prevent jumps. Override initial values.
-
-- The progress is clamped to a minimum value to avoid the line being empty, which can lead to turf errors
-- See [Timing](./timing.md) for more options for timing.
-- Consider the dimensions of the composition and make the lines thick enough and the label font size large enough to be legible for when the composition is scaled down.
-
-## Animating lines
-
-### Straight lines (linear interpolation)
-
-To animate a line that appears straight on the map, use linear interpolation between coordinates. Do NOT use turf's `lineSliceAlong` or `along` functions, as they use geodesic (great circle) calculations which appear curved on a Mercator projection.
-
-```tsx
-const frame = useCurrentFrame();
-const { durationInFrames } = useVideoConfig();
-
-useEffect(() => {
-  if (!map) return;
-
-  const animationHandle = delayRender("Animating line...");
-
-  const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
-    extrapolateLeft: "clamp",
-    extrapolateRight: "clamp",
-    easing: Easing.inOut(Easing.cubic),
-  });
-
-  // Linear interpolation for a straight line on the map
-  const start = lineCoordinates[0];
-  const end = lineCoordinates[1];
-  const currentLng = start[0] + (end[0] - start[0]) * progress;
-  const currentLat = start[1] + (end[1] - start[1]) * progress;
-
-  const lineData: GeoJSON.Feature<GeoJSON.LineString> = {
-    type: "Feature",
-    properties: {},
-    geometry: {
-      type: "LineString",
-      coordinates: [start, [currentLng, currentLat]],
-    },
-  };
-
-  const source = map.getSource("trace") as mapboxgl.GeoJSONSource;
-  if (source) {
-    source.setData(lineData);
-  }
-
-  map.once("idle", () => continueRender(animationHandle));
-}, [frame, map, durationInFrames]);
-```
-
-### Curved lines (geodesic/great circle)
-
-To animate a line that follows the geodesic (great circle) path between two points, use turf's `lineSliceAlong`. This is useful for showing flight paths or the actual shortest distance on Earth.
-
-```tsx
-import * as turf from "@turf/turf";
-
-const routeLine = turf.lineString(lineCoordinates);
-const routeDistance = turf.length(routeLine);
-
-const currentDistance = Math.max(0.001, routeDistance * progress);
-const slicedLine = turf.lineSliceAlong(routeLine, 0, currentDistance);
-
-const source = map.getSource("route") as mapboxgl.GeoJSONSource;
-if (source) {
-  source.setData(slicedLine);
-}
-```
-
-## Markers
-
-Add labels, and markers where appropriate.
-
-```tsx
-_map.addSource("markers", {
-  type: "geojson",
-  data: {
-    type: "FeatureCollection",
-    features: [
-      {
-        type: "Feature",
-        properties: { name: "Point 1" },
-        geometry: { type: "Point", coordinates: [-118.2437, 34.0522] },
-      },
-    ],
-  },
-});
-
-_map.addLayer({
-  id: "city-markers",
-  type: "circle",
-  source: "markers",
-  paint: {
-    "circle-radius": 40,
-    "circle-color": "#FF4444",
-    "circle-stroke-width": 4,
-    "circle-stroke-color": "#FFFFFF",
-  },
-});
-
-_map.addLayer({
-  id: "labels",
-  type: "symbol",
-  source: "markers",
-  layout: {
-    "text-field": ["get", "name"],
-    "text-font": ["DIN Pro Bold", "Arial Unicode MS Bold"],
-    "text-size": 50,
-    "text-offset": [0, 0.5],
-    "text-anchor": "top",
-  },
-  paint: {
-    "text-color": "#FFFFFF",
-    "text-halo-color": "#000000",
-    "text-halo-width": 2,
-  },
-});
-```
-
-Make sure they are big enough. Check the composition dimensions and scale the labels accordingly.
-For a composition size of 1920x1080, the label font size should be at least 40px.
-
-IMPORTANT: Keep the `text-offset` small enough so it is close to the marker. Consider the marker circle radius. For a circle radius of 40, this is a good offset:
-
-```tsx
-"text-offset": [0, 0.5],
-```
-
-## 3D buildings
-
-To enable 3D buildings, use the following code:
-
-```tsx
-_map.setConfigProperty("basemap", "show3dObjects", true);
-_map.setConfigProperty("basemap", "show3dLandmarks", true);
-_map.setConfigProperty("basemap", "show3dBuildings", true);
-```
-
-## Rendering
-
-When rendering a map animation, make sure to render with the following flags:
-
-```
-npx remotion render --gl=angle --concurrency=1
-```

.agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md

@@ -1,34 +0,0 @@
----
-name: measuring-dom-nodes
-description: Measuring DOM element dimensions in Remotion
-metadata:
-  tags: measure, layout, dimensions, getBoundingClientRect, scale
----
-
-# Measuring DOM nodes in Remotion
-
-Remotion applies a `scale()` transform to the video container, which affects values from `getBoundingClientRect()`. Use `useCurrentScale()` to get correct measurements.
-
-## Measuring element dimensions
-
-```tsx
-import { useCurrentScale } from "remotion";
-import { useRef, useEffect, useState } from "react";
-
-export const MyComponent = () => {
-  const ref = useRef<HTMLDivElement>(null);
-  const scale = useCurrentScale();
-  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
-
-  useEffect(() => {
-    if (!ref.current) return;
-    const rect = ref.current.getBoundingClientRect();
-    setDimensions({
-      width: rect.width / scale,
-      height: rect.height / scale,
-    });
-  }, [scale]);
-
-  return <div ref={ref}>Content to measure</div>;
-};
-```

.agents/skills/remotion-best-practices/rules/measuring-text.md

@@ -1,140 +0,0 @@
----
-name: measuring-text
-description: Measuring text dimensions, fitting text to containers, and checking overflow
-metadata:
-  tags: measure, text, layout, dimensions, fitText, fillTextBox
----
-
-# Measuring text in Remotion
-
-## Prerequisites
-
-Install @remotion/layout-utils if it is not already installed:
-
-```bash
-npx remotion add @remotion/layout-utils
-```
-
-## Measuring text dimensions
-
-Use `measureText()` to calculate the width and height of text:
-
-```tsx
-import { measureText } from "@remotion/layout-utils";
-
-const { width, height } = measureText({
-  text: "Hello World",
-  fontFamily: "Arial",
-  fontSize: 32,
-  fontWeight: "bold",
-});
-```
-
-Results are cached - duplicate calls return the cached result.
-
-## Fitting text to a width
-
-Use `fitText()` to find the optimal font size for a container:
-
-```tsx
-import { fitText } from "@remotion/layout-utils";
-
-const { fontSize } = fitText({
-  text: "Hello World",
-  withinWidth: 600,
-  fontFamily: "Inter",
-  fontWeight: "bold",
-});
-
-return (
-  <div
-    style={{
-      fontSize: Math.min(fontSize, 80), // Cap at 80px
-      fontFamily: "Inter",
-      fontWeight: "bold",
-    }}
-  >
-    Hello World
-  </div>
-);
-```
-
-## Checking text overflow
-
-Use `fillTextBox()` to check if text exceeds a box:
-
-```tsx
-import { fillTextBox } from "@remotion/layout-utils";
-
-const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
-
-const words = ["Hello", "World", "This", "is", "a", "test"];
-for (const word of words) {
-  const { exceedsBox } = box.add({
-    text: word + " ",
-    fontFamily: "Arial",
-    fontSize: 24,
-  });
-  if (exceedsBox) {
-    // Text would overflow, handle accordingly
-    break;
-  }
-}
-```
-
-## Best practices
-
-**Load fonts first:** Only call measurement functions after fonts are loaded.
-
-```tsx
-import { loadFont } from "@remotion/google-fonts/Inter";
-
-const { fontFamily, waitUntilDone } = loadFont("normal", {
-  weights: ["400"],
-  subsets: ["latin"],
-});
-
-waitUntilDone().then(() => {
-  // Now safe to measure
-  const { width } = measureText({
-    text: "Hello",
-    fontFamily,
-    fontSize: 32,
-  });
-});
-```
-
-**Use validateFontIsLoaded:** Catch font loading issues early:
-
-```tsx
-measureText({
-  text: "Hello",
-  fontFamily: "MyCustomFont",
-  fontSize: 32,
-  validateFontIsLoaded: true, // Throws if font not loaded
-});
-```
-
-**Match font properties:** Use the same properties for measurement and rendering:
-
-```tsx
-const fontStyle = {
-  fontFamily: "Inter",
-  fontSize: 32,
-  fontWeight: "bold" as const,
-  letterSpacing: "0.5px",
-};
-
-const { width } = measureText({
-  text: "Hello",
-  ...fontStyle,
-});
-
-return <div style={fontStyle}>Hello</div>;
-```
-
-**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
-
-```tsx
-<div style={{ outline: "2px solid red" }}>Text</div>
-```

.agents/skills/remotion-best-practices/rules/parameters.md

@@ -1,109 +0,0 @@
----
-name: parameters
-description: Make a video parametrizable by adding a Zod schema
-metadata:
-  tags: parameters, zod, schema
----
-
-To make a video parametrizable, a Zod schema can be added to a composition.
-
-First, `zod` must be installed .
-
-Search the project for lockfiles and run the correct command depending on the package manager:
-
-If `package-lock.json` is found, use the following command:
-
-```bash
-npm i zod
-```
-
-If `bun.lockb` is found, use the following command:
-
-```bash
-bun i zod
-```
-
-If `yarn.lock` is found, use the following command:
-
-```bash
-yarn add zod
-```
-
-If `pnpm-lock.yaml` is found, use the following command:
-
-```bash
-pnpm i zod
-```
-
-Then, a Zod schema can be defined alongside the component:
-
-```tsx title="src/MyComposition.tsx"
-import { z } from "zod";
-
-export const MyCompositionSchema = z.object({
-  title: z.string(),
-});
-
-const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
-  return (
-    <div>
-      <h1>{props.title}</h1>
-    </div>
-  );
-};
-```
-
-In the root file, the schema can be passed to the composition:
-
-```tsx title="src/Root.tsx"
-import { Composition } from "remotion";
-import { MycComponent, MyCompositionSchema } from "./MyComposition";
-
-export const RemotionRoot = () => {
-  return (
-    <Composition
-      id="MyComposition"
-      component={MyComponent}
-      durationInFrames={100}
-      fps={30}
-      width={1080}
-      height={1080}
-      defaultProps={{ title: "Hello World" }}
-      schema={MyCompositionSchema}
-    />
-  );
-};
-```
-
-Now, the user can edit the parameter visually in the sidebar.
-
-All schemas that are supported by Zod are supported by Remotion.
-
-Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.
-
-## Color picker
-
-For adding a color picker, use `zColor()` from `@remotion/zod-types`.
-
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/zod-types # If project uses npm
-bunx remotion add @remotion/zod-types # If project uses bun
-yarn remotion add @remotion/zod-types # If project uses yarn
-pnpm exec remotion add @remotion/zod-types # If project uses pnpm
-```
-
-Then import `zColor` from `@remotion/zod-types`:
-
-```tsx
-import { zColor } from "@remotion/zod-types";
-```
-
-Then use it in the schema:
-
-```tsx
-export const MyCompositionSchema = z.object({
-  color: zColor(),
-});
-```

.agents/skills/remotion-best-practices/rules/sequencing.md

@@ -1,118 +0,0 @@
----
-name: sequencing
-description: Sequencing patterns for Remotion - delay, trim, limit duration of items
-metadata:
-  tags: sequence, series, timing, delay, trim
----
-
-Use `<Sequence>` to delay when an element appears in the timeline.
-
-```tsx
-import { Sequence } from "remotion";
-
-const {fps} = useVideoConfig();
-
-<Sequence from={1 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
-  <Title />
-</Sequence>
-<Sequence from={2 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
-  <Subtitle />
-</Sequence>
-```
-
-This will by default wrap the component in an absolute fill element.  
-If the items should not be wrapped, use the `layout` prop:
-
-```tsx
-<Sequence layout="none">
-  <Title />
-</Sequence>
-```
-
-## Premounting
-
-This loads the component in the timeline before it is actually played.  
-Always premount any `<Sequence>`!
-
-```tsx
-<Sequence premountFor={1 * fps}>
-  <Title />
-</Sequence>
-```
-
-## Series
-
-Use `<Series>` when elements should play one after another without overlap.
-
-```tsx
-import { Series } from "remotion";
-
-<Series>
-  <Series.Sequence durationInFrames={45}>
-    <Intro />
-  </Series.Sequence>
-  <Series.Sequence durationInFrames={60}>
-    <MainContent />
-  </Series.Sequence>
-  <Series.Sequence durationInFrames={30}>
-    <Outro />
-  </Series.Sequence>
-</Series>;
-```
-
-Same as with `<Sequence>`, the items will be wrapped in an absolute fill element by default when using `<Series.Sequence>`, unless the `layout` prop is set to `none`.
-
-### Series with overlaps
-
-Use negative offset for overlapping sequences:
-
-```tsx
-<Series>
-  <Series.Sequence durationInFrames={60}>
-    <SceneA />
-  </Series.Sequence>
-  <Series.Sequence offset={-15} durationInFrames={60}>
-    {/* Starts 15 frames before SceneA ends */}
-    <SceneB />
-  </Series.Sequence>
-</Series>
-```
-
-## Frame References Inside Sequences
-
-Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
-
-```tsx
-<Sequence from={60} durationInFrames={30}>
-  <MyComponent />
-  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
-</Sequence>
-```
-
-## Nested Sequences
-
-Sequences can be nested for complex timing:
-
-```tsx
-<Sequence from={0} durationInFrames={120}>
-  <Background />
-  <Sequence from={15} durationInFrames={90} layout="none">
-    <Title />
-  </Sequence>
-  <Sequence from={45} durationInFrames={60} layout="none">
-    <Subtitle />
-  </Sequence>
-</Sequence>
-```
-
-## Nesting compositions within another
-
-To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
-
-```tsx
-<AbsoluteFill>
-  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
-    <CompositionComponent />
-  </Sequence>
-</AbsoluteFill>
-```

.agents/skills/remotion-best-practices/rules/sfx.md

@@ -1,26 +0,0 @@
----
-name: sfx
-description: Including sound effects
-metadata:
-  tags: sfx, sound, effect, audio
----
-
-To include a sound effect, use the `<Audio>` tag:
-
-```tsx
-import { Audio } from "@remotion/sfx";
-
-<Audio src={"https://remotion.media/whoosh.wav"} />;
-```
-
-The following sound effects are available:
-
-- `https://remotion.media/whoosh.wav`
-- `https://remotion.media/whip.wav`
-- `https://remotion.media/page-turn.wav`
-- `https://remotion.media/switch.wav`
-- `https://remotion.media/mouse-click.wav`
-- `https://remotion.media/shutter-modern.wav`
-- `https://remotion.media/shutter-old.wav`
-
-For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.

.agents/skills/remotion-best-practices/rules/subtitles.md

@@ -1,36 +0,0 @@
----
-name: subtitles
-description: subtitles and caption rules
-metadata:
-  tags: subtitles, captions, remotion, json
----
-
-All captions must be processed in JSON. The captions must use the `Caption` type which is the following:
-
-```ts
-import type { Caption } from "@remotion/captions";
-```
-
-This is the definition:
-
-```ts
-type Caption = {
-  text: string;
-  startMs: number;
-  endMs: number;
-  timestampMs: number | null;
-  confidence: number | null;
-};
-```
-
-## Generating captions
-
-To transcribe video and audio files to generate captions, load the [./transcribe-captions.md](./transcribe-captions.md) file for more instructions.
-
-## Displaying captions
-
-To display captions in your video, load the [./display-captions.md](./display-captions.md) file for more instructions.
-
-## Importing captions
-
-To import captions from a .srt file, load the [./import-srt-captions.md](./import-srt-captions.md) file for more instructions.

.agents/skills/remotion-best-practices/rules/tailwind.md

@@ -1,11 +0,0 @@
----
-name: tailwind
-description: Using TailwindCSS in Remotion.
-metadata:
----
-
-You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.
-
-Don't use `transition-*` or `animate-*` classes - always animate using the `useCurrentFrame()` hook.
-
-Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.

.agents/skills/remotion-best-practices/rules/text-animations.md

@@ -1,20 +0,0 @@
----
-name: text-animations
-description: Typography and text animation patterns for Remotion.
-metadata:
-  tags: typography, text, typewriter, highlighter ken
----
-
-## Text animations
-
-Based on `useCurrentFrame()`, reduce the string character by character to create a typewriter effect.
-
-## Typewriter Effect
-
-See [Typewriter](assets/text-animations-typewriter.tsx) for an advanced example with a blinking cursor and a pause after the first sentence.
-
-Always use string slicing for typewriter effects. Never use per-character opacity.
-
-## Word Highlighting
-
-See [Word Highlight](assets/text-animations-word-highlight.tsx) for an example for how a word highlight is animated, like with a highlighter pen.

.agents/skills/remotion-best-practices/rules/timing.md

@@ -1,179 +0,0 @@
----
-name: timing
-description: Interpolation curves in Remotion - linear, easing, spring animations
-metadata:
-  tags: spring, bounce, easing, interpolation
----
-
-A simple linear interpolation is done using the `interpolate` function.
-
-```ts title="Going from 0 to 1 over 100 frames"
-import { interpolate } from "remotion";
-
-const opacity = interpolate(frame, [0, 100], [0, 1]);
-```
-
-By default, the values are not clamped, so the value can go outside the range [0, 1].  
-Here is how they can be clamped:
-
-```ts title="Going from 0 to 1 over 100 frames with extrapolation"
-const opacity = interpolate(frame, [0, 100], [0, 1], {
-  extrapolateRight: "clamp",
-  extrapolateLeft: "clamp",
-});
-```
-
-## Spring animations
-
-Spring animations have a more natural motion.  
-They go from 0 to 1 over time.
-
-```ts title="Spring animation from 0 to 1 over 100 frames"
-import { spring, useCurrentFrame, useVideoConfig } from "remotion";
-
-const frame = useCurrentFrame();
-const { fps } = useVideoConfig();
-
-const scale = spring({
-  frame,
-  fps,
-});
-```
-
-### Physical properties
-
-The default configuration is: `mass: 1, damping: 10, stiffness: 100`.  
-This leads to the animation having a bit of bounce before it settles.
-
-The config can be overwritten like this:
-
-```ts
-const scale = spring({
-  frame,
-  fps,
-  config: { damping: 200 },
-});
-```
-
-The recommended configuration for a natural motion without a bounce is: `{ damping: 200 }`.
-
-Here are some common configurations:
-
-```tsx
-const smooth = { damping: 200 }; // Smooth, no bounce (subtle reveals)
-const snappy = { damping: 20, stiffness: 200 }; // Snappy, minimal bounce (UI elements)
-const bouncy = { damping: 8 }; // Bouncy entrance (playful animations)
-const heavy = { damping: 15, stiffness: 80, mass: 2 }; // Heavy, slow, small bounce
-```
-
-### Delay
-
-The animation starts immediately by default.  
-Use the `delay` parameter to delay the animation by a number of frames.
-
-```tsx
-const entrance = spring({
-  frame: frame - ENTRANCE_DELAY,
-  fps,
-  delay: 20,
-});
-```
-
-### Duration
-
-A `spring()` has a natural duration based on the physical properties.  
-To stretch the animation to a specific duration, use the `durationInFrames` parameter.
-
-```tsx
-const spring = spring({
-  frame,
-  fps,
-  durationInFrames: 40,
-});
-```
-
-### Combining spring() with interpolate()
-
-Map spring output (0-1) to custom ranges:
-
-```tsx
-const springProgress = spring({
-  frame,
-  fps,
-});
-
-// Map to rotation
-const rotation = interpolate(springProgress, [0, 1], [0, 360]);
-
-<div style={{ rotate: rotation + "deg" }} />;
-```
-
-### Adding springs
-
-Springs return just numbers, so math can be performed:
-
-```tsx
-const frame = useCurrentFrame();
-const { fps, durationInFrames } = useVideoConfig();
-
-const inAnimation = spring({
-  frame,
-  fps,
-});
-const outAnimation = spring({
-  frame,
-  fps,
-  durationInFrames: 1 * fps,
-  delay: durationInFrames - 1 * fps,
-});
-
-const scale = inAnimation - outAnimation;
-```
-
-## Easing
-
-Easing can be added to the `interpolate` function:
-
-```ts
-import { interpolate, Easing } from "remotion";
-
-const value1 = interpolate(frame, [0, 100], [0, 1], {
-  easing: Easing.inOut(Easing.quad),
-  extrapolateLeft: "clamp",
-  extrapolateRight: "clamp",
-});
-```
-
-The default easing is `Easing.linear`.  
-There are various other convexities:
-
-- `Easing.in` for starting slow and accelerating
-- `Easing.out` for starting fast and slowing down
-- `Easing.inOut`
-
-and curves (sorted from most linear to most curved):
-
-- `Easing.quad`
-- `Easing.sin`
-- `Easing.exp`
-- `Easing.circle`
-
-Convexities and curves need be combined for an easing function:
-
-```ts
-const value1 = interpolate(frame, [0, 100], [0, 1], {
-  easing: Easing.inOut(Easing.quad),
-  extrapolateLeft: "clamp",
-  extrapolateRight: "clamp",
-});
-```
-
-Cubic bezier curves are also supported:
-
-```ts
-const value1 = interpolate(frame, [0, 100], [0, 1], {
-  easing: Easing.bezier(0.8, 0.22, 0.96, 0.65),
-  extrapolateLeft: "clamp",
-  extrapolateRight: "clamp",
-});
-```

.agents/skills/remotion-best-practices/rules/transcribe-captions.md

@@ -1,70 +0,0 @@
----
-name: transcribe-captions
-description: Transcribing audio to generate captions in Remotion
-metadata:
-  tags: captions, transcribe, whisper, audio, speech-to-text
----
-
-# Transcribing audio
-
-To transcribe audio to generate captions in Remotion, you can use the [`transcribe()`](https://www.remotion.dev/docs/install-whisper-cpp/transcribe) function from the [`@remotion/install-whisper-cpp`](https://www.remotion.dev/docs/install-whisper-cpp) package.
-
-## Prerequisites
-
-First, the @remotion/install-whisper-cpp package needs to be installed.
-If it is not installed, use the following command:
-
-```bash
-npx remotion add @remotion/install-whisper-cpp
-```
-
-## Transcribing
-
-Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.
-
-```ts
-import path from "path";
-import {
-  downloadWhisperModel,
-  installWhisperCpp,
-  transcribe,
-  toCaptions,
-} from "@remotion/install-whisper-cpp";
-import fs from "fs";
-
-const to = path.join(process.cwd(), "whisper.cpp");
-
-await installWhisperCpp({
-  to,
-  version: "1.5.5",
-});
-
-await downloadWhisperModel({
-  model: "medium.en",
-  folder: to,
-});
-
-// Convert the audio to a 16KHz wav file first if needed:
-// import {execSync} from 'child_process';
-// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
-
-const whisperCppOutput = await transcribe({
-  model: "medium.en",
-  whisperPath: to,
-  whisperCppVersion: "1.5.5",
-  inputPath: "/path/to/audio123.wav",
-  tokenLevelTimestamps: true,
-});
-
-// Optional: Apply our recommended postprocessing
-const { captions } = toCaptions({
-  whisperCppOutput,
-});
-
-// Write it to the public/ folder so it can be fetched from Remotion
-fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));
-```
-
-Transcribe each clip individually and create multiple JSON files.
-
-See [Displaying captions](display-captions.md) for how to display the captions in Remotion.

.agents/skills/remotion-best-practices/rules/transitions.md

@@ -1,197 +0,0 @@
----
-name: transitions
-description: Scene transitions and overlays for Remotion using TransitionSeries.
-metadata:
-  tags: transitions, overlays, fade, slide, wipe, scenes
----
-
-## TransitionSeries
-
-`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
-
-- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
-- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
-
-Children are absolutely positioned.
-
-## Prerequisites
-
-```bash
-npx remotion add @remotion/transitions
-```
-
-## Transition example
-
-```tsx
-import { TransitionSeries, linearTiming } from "@remotion/transitions";
-import { fade } from "@remotion/transitions/fade";
-
-<TransitionSeries>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneA />
-  </TransitionSeries.Sequence>
-  <TransitionSeries.Transition
-    presentation={fade()}
-    timing={linearTiming({ durationInFrames: 15 })}
-  />
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneB />
-  </TransitionSeries.Sequence>
-</TransitionSeries>;
-```
-
-## Overlay example
-
-Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
-
-```tsx
-import { TransitionSeries } from "@remotion/transitions";
-import { LightLeak } from "@remotion/light-leaks";
-
-<TransitionSeries>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneA />
-  </TransitionSeries.Sequence>
-  <TransitionSeries.Overlay durationInFrames={20}>
-    <LightLeak />
-  </TransitionSeries.Overlay>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneB />
-  </TransitionSeries.Sequence>
-</TransitionSeries>;
-```
-
-## Mixing transitions and overlays
-
-Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
-
-```tsx
-import { TransitionSeries, linearTiming } from "@remotion/transitions";
-import { fade } from "@remotion/transitions/fade";
-import { LightLeak } from "@remotion/light-leaks";
-
-<TransitionSeries>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneA />
-  </TransitionSeries.Sequence>
-  <TransitionSeries.Overlay durationInFrames={30}>
-    <LightLeak />
-  </TransitionSeries.Overlay>
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneB />
-  </TransitionSeries.Sequence>
-  <TransitionSeries.Transition
-    presentation={fade()}
-    timing={linearTiming({ durationInFrames: 15 })}
-  />
-  <TransitionSeries.Sequence durationInFrames={60}>
-    <SceneC />
-  </TransitionSeries.Sequence>
-</TransitionSeries>;
-```
-
-## Transition props
-
-`<TransitionSeries.Transition>` requires:
-
-- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
-- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
-
-## Overlay props
-
-`<TransitionSeries.Overlay>` accepts:
-
-- `durationInFrames` — how long the overlay is visible (positive integer).
-- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
-
-## Available transition types
-
-Import transitions from their respective modules:
-
-```tsx
-import { fade } from "@remotion/transitions/fade";
-import { slide } from "@remotion/transitions/slide";
-import { wipe } from "@remotion/transitions/wipe";
-import { flip } from "@remotion/transitions/flip";
-import { clockWipe } from "@remotion/transitions/clock-wipe";
-```
-
-## Slide transition with direction
-
-```tsx
-import { slide } from "@remotion/transitions/slide";
-
-<TransitionSeries.Transition
-  presentation={slide({ direction: "from-left" })}
-  timing={linearTiming({ durationInFrames: 20 })}
-/>;
-```
-
-Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
-
-## Timing options
-
-```tsx
-import { linearTiming, springTiming } from "@remotion/transitions";
-
-// Linear timing - constant speed
-linearTiming({ durationInFrames: 20 });
-
-// Spring timing - organic motion
-springTiming({ config: { damping: 200 }, durationInFrames: 25 });
-```
-
-## Duration calculation
-
-Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
-
-For example, with two 60-frame sequences and a 15-frame transition:
-
-- Without transitions: `60 + 60 = 120` frames
-- With transition: `60 + 60 - 15 = 105` frames
-
-Adding an overlay between two other sequences does not change the total.
-
-### Getting the duration of a transition
-
-Use the `getDurationInFrames()` method on the timing object:
-
-```tsx
-import { linearTiming, springTiming } from "@remotion/transitions";
-
-const linearDuration = linearTiming({
-  durationInFrames: 20,
-}).getDurationInFrames({ fps: 30 });
-// Returns 20
-
-const springDuration = springTiming({
-  config: { damping: 200 },
-}).getDurationInFrames({ fps: 30 });
-// Returns calculated duration based on spring physics
-```
-
-For `springTiming` without an explicit `durationInFrames`, the duration depends on `fps` because it calculates when the spring animation settles.
-
-### Calculating total composition duration
-
-```tsx
-import { linearTiming } from "@remotion/transitions";
-
-const scene1Duration = 60;
-const scene2Duration = 60;
-const scene3Duration = 60;
-
-const timing1 = linearTiming({ durationInFrames: 15 });
-const timing2 = linearTiming({ durationInFrames: 20 });
-
-const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
-const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
-
-const totalDuration =
-  scene1Duration +
-  scene2Duration +
-  scene3Duration -
-  transition1Duration -
-  transition2Duration;
-// 60 + 60 + 60 - 15 - 20 = 145 frames
-```

.agents/skills/remotion-best-practices/rules/transparent-videos.md

@@ -1,106 +0,0 @@
----
-name: transparent-videos
-description: Rendering transparent videos in Remotion
-metadata:
-  tags: transparent, alpha, codec, vp9, prores, webm
----
-
-# Rendering Transparent Videos
-
-Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
-
-## Transparent ProRes
-
-Ideal for when importing into video editing software.
-
-**CLI:**
-
-```bash
-npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
-```
-
-**Default in Studio** (restart Studio after changing):
-
-```ts
-// remotion.config.ts
-import { Config } from "@remotion/cli/config";
-
-Config.setVideoImageFormat("png");
-Config.setPixelFormat("yuva444p10le");
-Config.setCodec("prores");
-Config.setProResProfile("4444");
-```
-
-**Setting it as the default export settings for a composition** (using `calculateMetadata`):
-
-```tsx
-import { CalculateMetadataFunction } from "remotion";
-
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  return {
-    defaultCodec: "prores",
-    defaultVideoImageFormat: "png",
-    defaultPixelFormat: "yuva444p10le",
-    defaultProResProfile: "4444",
-  };
-};
-
-<Composition
-  id="my-video"
-  component={MyVideo}
-  durationInFrames={150}
-  fps={30}
-  width={1920}
-  height={1080}
-  calculateMetadata={calculateMetadata}
-/>;
-```
-
-## Transparent WebM (VP9)
-
-Ideal for when playing in a browser.
-
-**CLI:**
-
-```bash
-npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
-```
-
-**Default in Studio** (restart Studio after changing):
-
-```ts
-// remotion.config.ts
-import { Config } from "@remotion/cli/config";
-
-Config.setVideoImageFormat("png");
-Config.setPixelFormat("yuva420p");
-Config.setCodec("vp9");
-```
-
-**Setting it as the default export settings for a composition** (using `calculateMetadata`):
-
-```tsx
-import { CalculateMetadataFunction } from "remotion";
-
-const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  return {
-    defaultCodec: "vp8",
-    defaultVideoImageFormat: "png",
-    defaultPixelFormat: "yuva420p",
-  };
-};
-
-<Composition
-  id="my-video"
-  component={MyVideo}
-  durationInFrames={150}
-  fps={30}
-  width={1920}
-  height={1080}
-  calculateMetadata={calculateMetadata}
-/>;
-```

.agents/skills/remotion-best-practices/rules/trimming.md

@@ -1,51 +0,0 @@
----
-name: trimming
-description: Trimming patterns for Remotion - cut the beginning or end of animations
-metadata:
-  tags: sequence, trim, clip, cut, offset
----
-
-Use `<Sequence>` with a negative `from` value to trim the start of an animation.
-
-## Trim the Beginning
-
-A negative `from` value shifts time backwards, making the animation start partway through:
-
-```tsx
-import { Sequence, useVideoConfig } from "remotion";
-
-const fps = useVideoConfig();
-
-<Sequence from={-0.5 * fps}>
-  <MyAnimation />
-</Sequence>;
-```
-
-The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
-Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
-
-## Trim the End
-
-Use `durationInFrames` to unmount content after a specified duration:
-
-```tsx
-<Sequence durationInFrames={1.5 * fps}>
-  <MyAnimation />
-</Sequence>
-```
-
-The animation plays for 45 frames, then the component unmounts.
-
-## Trim and Delay
-
-Nest sequences to both trim the beginning and delay when it appears:
-
-```tsx
-<Sequence from={30}>
-  <Sequence from={-15}>
-    <MyAnimation />
-  </Sequence>
-</Sequence>
-```
-
-The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.

.agents/skills/remotion-best-practices/rules/videos.md

@@ -1,171 +0,0 @@
----
-name: videos
-description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
-metadata:
-  tags: video, media, trim, volume, speed, loop, pitch
----
-
-# Using videos in Remotion
-
-## Prerequisites
-
-First, the @remotion/media package needs to be installed.  
-If it is not, use the following command:
-
-```bash
-npx remotion add @remotion/media # If project uses npm
-bunx remotion add @remotion/media # If project uses bun
-yarn remotion add @remotion/media # If project uses yarn
-pnpm exec remotion add @remotion/media # If project uses pnpm
-```
-
-Use `<Video>` from `@remotion/media` to embed videos into your composition.
-
-```tsx
-import { Video } from "@remotion/media";
-import { staticFile } from "remotion";
-
-export const MyComposition = () => {
-  return <Video src={staticFile("video.mp4")} />;
-};
-```
-
-Remote URLs are also supported:
-
-```tsx
-<Video src="https://remotion.media/video.mp4" />
-```
-
-## Trimming
-
-Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
-
-```tsx
-const { fps } = useVideoConfig();
-
-return (
-  <Video
-    src={staticFile("video.mp4")}
-    trimBefore={2 * fps} // Skip the first 2 seconds
-    trimAfter={10 * fps} // End at the 10 second mark
-  />
-);
-```
-
-## Delaying
-
-Wrap the video in a `<Sequence>` to delay when it appears:
-
-```tsx
-import { Sequence, staticFile } from "remotion";
-import { Video } from "@remotion/media";
-
-const { fps } = useVideoConfig();
-
-return (
-  <Sequence from={1 * fps}>
-    <Video src={staticFile("video.mp4")} />
-  </Sequence>
-);
-```
-
-The video will appear after 1 second.
-
-## Sizing and Position
-
-Use the `style` prop to control size and position:
-
-```tsx
-<Video
-  src={staticFile("video.mp4")}
-  style={{
-    width: 500,
-    height: 300,
-    position: "absolute",
-    top: 100,
-    left: 50,
-    objectFit: "cover",
-  }}
-/>
-```
-
-## Volume
-
-Set a static volume (0 to 1):
-
-```tsx
-<Video src={staticFile("video.mp4")} volume={0.5} />
-```
-
-Or use a callback for dynamic volume based on the current frame:
-
-```tsx
-import { interpolate } from "remotion";
-
-const { fps } = useVideoConfig();
-
-return (
-  <Video
-    src={staticFile("video.mp4")}
-    volume={(f) =>
-      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
-    }
-  />
-);
-```
-
-Use `muted` to silence the video entirely:
-
-```tsx
-<Video src={staticFile("video.mp4")} muted />
-```
-
-## Speed
-
-Use `playbackRate` to change the playback speed:
-
-```tsx
-<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
-<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
-```
-
-Reverse playback is not supported.
-
-## Looping
-
-Use `loop` to loop the video indefinitely:
-
-```tsx
-<Video src={staticFile("video.mp4")} loop />
-```
-
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
-- `"extend"`: Frame count continues incrementing
-
-```tsx
-<Video
-  src={staticFile("video.mp4")}
-  loop
-  loopVolumeCurveBehavior="extend"
-  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
-```
-
-## Pitch
-
-Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
-
-```tsx
-<Video
-  src={staticFile("video.mp4")}
-  toneFrequency={1.5} // Higher pitch
-/>
-<Video
-  src={staticFile("video.mp4")}
-  toneFrequency={0.8} // Lower pitch
-/>
-```
-
-Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

.agents/skills/remotion-best-practices/rules/voiceover.md

@@ -1,99 +0,0 @@
----
-name: voiceover
-description: Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
-metadata:
-  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
----
-
-# Adding AI voiceover to a Remotion composition
-
-Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
-
-## Prerequisites
-
-An **ElevenLabs API key** is required (`ELEVENLABS_API_KEY` environment variable).
-
-**MUST** ask the user for their ElevenLabs API key if `ELEVENLABS_API_KEY` is not set. **MUST NOT** fall back to other TTS tools.
-
-Ensure the environment variable is available when running the generation script:
-
-```bash
-node --strip-types generate-voiceover.ts
-```
-
-## Generating audio with ElevenLabs
-
-Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
-
-The core API call for a single scene:
-
-```ts title="generate-voiceover.ts"
-const response = await fetch(
-  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
-  {
-    method: "POST",
-    headers: {
-      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
-      "Content-Type": "application/json",
-      Accept: "audio/mpeg",
-    },
-    body: JSON.stringify({
-      text: "Welcome to the show.",
-      model_id: "eleven_multilingual_v2",
-      voice_settings: {
-        stability: 0.5,
-        similarity_boost: 0.75,
-        style: 0.3,
-      },
-    }),
-  },
-);
-
-const audioBuffer = Buffer.from(await response.arrayBuffer());
-writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
-```
-
-## Dynamic composition duration with calculateMetadata
-
-Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
-
-```tsx
-import { CalculateMetadataFunction, staticFile } from "remotion";
-import { getAudioDuration } from "./get-audio-duration";
-
-const FPS = 30;
-
-const SCENE_AUDIO_FILES = [
-  "voiceover/my-comp/scene-01-intro.mp3",
-  "voiceover/my-comp/scene-02-main.mp3",
-  "voiceover/my-comp/scene-03-outro.mp3",
-];
-
-export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
-  props,
-}) => {
-  const durations = await Promise.all(
-    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
-  );
-
-  const sceneDurations = durations.map((durationInSeconds) => {
-    return durationInSeconds * FPS;
-  });
-
-  return {
-    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
-  };
-};
-```
-
-The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
-
-If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
-
-## Rendering audio in the component
-
-See [audio.md](./audio.md) for more information on how to render audio in the component.
-
-## Delaying audio start
-
-See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/SECURITY.md

@@ -0,0 +1,78 @@
+# Security Policy
+
+Codeman launches AI coding sessions with `--dangerously-skip-permissions`, so the
+web UI is **by design a remote-code-execution surface for whoever can reach it**.
+The entire security model exists to control *who* that is. Please read this before
+exposing an instance beyond `localhost`. The full model lives in
+[`docs/security-architecture.md`](../docs/security-architecture.md).
+
+## Supported versions
+
+Security fixes land on the latest published `codeman@X.Y.Z` release and `master`.
+Older versions are not patched — upgrade to the latest release (App Settings →
+Updates for git-clone installs, or `npm i -g aicodeman@latest`).
+
+| Version | Supported |
+| ------- | --------- |
+| latest `0.9.x` / `master` | ✅ |
+| anything older | ❌ (upgrade) |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security problems.**
+
+Report privately via **GitHub's private vulnerability reporting**:
+the repository's **Security** tab → **Report a vulnerability**
+(<https://github.com/Ark0N/Codeman/security/advisories/new>). This opens a private
+advisory thread with the maintainer.
+
+> Maintainer note: enable *Settings → Code security and analysis → Private
+> vulnerability reporting* so this channel is live.
+
+When reporting, please include: affected version/commit, the deployment shape
+(loopback-only, `CODEMAN_PASSWORD` set, tunnel/`tailscale serve`, custom
+reverse proxy), reproduction steps, and impact. We aim to acknowledge within a
+few days. Coordinated disclosure is appreciated — we'll agree a disclosure
+timeline with you once impact is confirmed.
+
+### In scope
+- Authentication / session-cookie bypass when `CODEMAN_PASSWORD` is set
+- DNS-rebinding, CSRF/CSWSH, or Origin/Host-guard bypass reaching state-changing routes
+- Remote code execution reachable **without** local OS access (e.g. via a browser, a tunnel, or a foreign origin)
+- Path traversal / arbitrary file read or write through the HTTP API
+- Supply-chain integrity of the in-app self-updater
+
+### Out of scope (by design — see Known limitations)
+- Anything requiring an already-trusted **same-machine, same-uid** process. Codeman trusts the local OS user it runs as; a peer process of that user is already inside the boundary.
+- Running an authless instance bound to a non-loopback host after dismissing the startup warning (you explicitly acknowledged it).
+- The default loopback + no-password posture itself (it is reachable only from the same machine).
+
+## Trust model (summary)
+
+- **Loopback by default.** Binds `127.0.0.1`; the no-password default is safe out of the box. Binding a non-loopback host without `CODEMAN_PASSWORD` *starts but prints a loud warning* with concrete fixes.
+- **Always-on Host + Origin guards.** Block DNS-rebinding and cross-site state-changing requests even on the no-auth loopback install (a missing Origin is allowed so CLI/hooks work).
+- **Optional auth.** HTTP Basic via `CODEMAN_USERNAME`/`CODEMAN_PASSWORD`; success issues an opaque server-side 256-bit cookie. Per-IP rate limiting on failures.
+- **Hardened file serving, tmux launch, transport headers, and multi-instance isolation** — see the full architecture doc.
+
+## Known limitations and accepted risk
+
+A 1.0 release is an implicit statement that the documented model *is* the model, so
+these residuals are stated explicitly. Most sit **inside the same-uid OS trust
+boundary** or behind the always-on Origin guard; they matter mainly for
+shared-host, multi-user, or tunneled deployments.
+
+- **Self-update trusts an unsigned release tag.** The in-app updater does `git checkout <tag> && npm install` (lifecycle scripts run) of a tag matched only by name shape, from whatever `origin` points to — no signature/commit verification. Treat the updater as trusting your `origin` remote and your release pipeline. (Hardening tracked for 1.0.)
+- **CSP ships `'unsafe-inline'`.** Inline handlers mean the Content-Security-Policy is defense-in-depth only; all AI-/file-derived sinks are escaped, but a future missed escape would be executable.
+- **`workingDir` is unconstrained.** A session may be created with any absolute working directory (e.g. `/`), which becomes the file-route boundary for that session. Scope it to trusted paths on shared hosts.
+- **Hook-event auth exemption is loopback-IP-based.** `POST /api/hook-event` is exempt from auth for loopback callers; because tunnels (cloudflared / `tailscale serve`) terminate at `127.0.0.1`, a loopback-terminating tunnel inherits the exemption. Set `CODEMAN_PASSWORD` and prefer a tunnel that preserves the client identity if this matters.
+- **Session cookie is not bound to client IP/UA on reuse, and refreshes without an absolute cap.** A stolen cookie replays until its idle TTL elapses.
+- **Multi-instance tmux socket is process-wide.** Two Codeman instances on the same `CODEMAN_INSTANCE` share a tmux socket and can attach each other's live sessions — isolate with distinct `CODEMAN_INSTANCE` values.
+- **The live log-tail route reads `/var/log` and `~/logs`** in addition to the session working directory (read-only) — a deliberate choice for tailing system/app logs. On a password-protected remote deployment an authenticated user can therefore read those roots outside their session. See `docs/security-architecture.md` §5.
+
+Recent hardening (this release): web-push subscription endpoints are restricted
+to https public hosts (SSRF guard — rejects internal/metadata IPs, validated at
+subscribe and send time), and tmux session names discovered on the shared socket
+are validated against the safe-name pattern before reaching any shell call site.
+
+For the detailed rationale, defenses, and recommended secure setups, see
+[`docs/security-architecture.md`](../docs/security-architecture.md).

.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  ci:
+    name: Typecheck & Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check package-lock.json version sync
+        run: npm run check:lockfile
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Frontend JS syntax check
+        run: npm run check:frontend-syntax
+
+      - name: Format check
+        run: npm run format:check
+
+      - name: Server boot smoke test
+        run: |
+          set -u
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+          npx tsx src/index.ts web --port 3151 > /tmp/boot.log 2>&1 &
+          SERVER_PID=$!
+          trap "kill $SERVER_PID 2>/dev/null || true" EXIT
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:3151/api/status -o /dev/null; then
+              echo "Server booted in ${i}s"
+              exit 0
+            fi
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "Server exited before becoming ready. Logs:"
+              cat /tmp/boot.log
+              exit 1
+            fi
+            sleep 1
+          done
+          echo "Server did not respond on /api/status within 30s. Logs:"
+          cat /tmp/boot.log
+          exit 1
+
+  test:
+    name: Unit & integration tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install tmux
+        run: |
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+
+      - name: Run unit & integration tests
+        # Excludes the browser-driven mobile suite (test/mobile/**); see config/vitest.ci.config.ts.
+        # Safe in CI: TmuxManager no-ops all shell commands under VITEST (test/setup.ts).
+        run: npm run test:ci
+
+# Note: The browser-driven mobile suite (test/mobile/**) is excluded from CI —
+# it needs a live server + chromium + environment-specific PNG baselines.
+# Run it locally/manually. All other tests run via the `test` job above.

.github/workflows/release.yml

@@ -11,15 +11,19 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
+          registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: npm ci
@@ -37,4 +41,26 @@ jobs:
           commit: "chore: version packages"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Rename release tag to codeman
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          OLD_TAG="aicodeman@${VERSION}"
+          NEW_TAG="codeman@${VERSION}"
+
+          # Update the GitHub release BEFORE deleting the old tag
+          RELEASE_ID=$(gh release view "$OLD_TAG" --json databaseId -q .databaseId 2>/dev/null || true)
+          if [ -n "$RELEASE_ID" ]; then
+            gh api -X PATCH "repos/${{ github.repository }}/releases/${RELEASE_ID}" \
+              -f tag_name="$NEW_TAG" \
+              -f name="$NEW_TAG"
+          fi
+
+          # Retag
+          git tag "$NEW_TAG" "$OLD_TAG" 2>/dev/null || true
+          git tag -d "$OLD_TAG" 2>/dev/null || true
+          git push origin "$NEW_TAG" ":refs/tags/$OLD_TAG" 2>/dev/null || true

.gitignore

@@ -1,3 +1,10 @@
+# Claude Code local files
+.agents/
+skills-lock.json
+
+# Written by install.sh into end-user clones when setup finishes
+.install-complete
+
 # Dependencies
 node_modules/
 
@@ -14,6 +21,10 @@ coverage/
 test/e2e/screenshots/current/
 test/e2e/screenshots/diffs/
 
+# Mobile visual regression failure artifacts
+test/mobile/snapshots/*.actual.png
+test/mobile/snapshots/*.diff.png
+
 # Logs
 *.log
 npm-debug.log*
@@ -41,6 +52,44 @@ Thumbs.db
 *.tmp
 *.temp
 
+# Generated output
+out/
+screenshots-echo-diag/
+screenshots-readme/
+screenshots-readme-real/
+screenshots-real/
+scripts/remotion/out/
+
+# Local UI/README capture scratch (screenshot runs, design mockups). Not build
+# output, but never meant for git — an unqualified `git add -A` during a COM has
+# swept dirs like these into a release before.
+design-explorations/
+
+# Artifacts that should not be tracked
+test-results/
+tmp/
+# Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
+# with a leading slash so it does NOT also match src/web/public (a bare `public`
+# would swallow the whole web UI source dir and silently un-stage any new asset
+# added there). No trailing slash so it still matches the symlink, not just dirs.
+/public
+
+# Opt-in gesture overlay runtime assets: large MediaPipe wasm + model (~27 MB)
+# fetched at build/install by scripts/fetch-gesture-assets.mjs, kept out of git.
+# (The gesture bundle itself, gesture-codeman.js, IS tracked — built from
+# packages/gesture-control source by `npm run build:gesture`.)
+src/web/public/gesture/wasm/
+src/web/public/gesture/*.task
+
+# Gesture-control workspace package build outputs (source is tracked; the
+# Codeman bundle is emitted to src/web/public/gesture/gesture-codeman.js instead).
+packages/gesture-control/dist/
+packages/gesture-control/dist-codeman/
+packages/gesture-control/.vite/
+
+# Claude Code plan tracking
+plan.json
+
 # Unfinished TUI (local development only)
 src/tui/
 .claude/
@@ -48,3 +97,7 @@ media-assets/
 commands
 todo.md
 @fix_plan.md
+readme-preview.mjs
+
+# Uploaded images land here under each session working dir (runtime artifact)
+.claude-images/

.nvmrc

@@ -0,0 +1 @@
+22

.prettierignore

@@ -0,0 +1,31 @@
+dist/
+coverage/
+node_modules/
+src/web/public/vendor/
+src/web/public/gesture/
+src/web/public/app.js
+src/web/public/styles.css
+src/web/public/mobile.css
+src/web/public/index.html
+# Hand-formatted public JS modules (never prettier-enforced; the new
+# check-public-assets.mjs still validates NUL bytes + JS syntax on these).
+src/web/public/constants.js
+src/web/public/image-input.js
+src/web/public/input-cjk.js
+src/web/public/keyboard-accessory.js
+src/web/public/notification-manager.js
+src/web/public/orchestrator-panel.js
+src/web/public/panels-ui.js
+src/web/public/ralph-panel.js
+src/web/public/ralph-wizard.js
+src/web/public/respawn-ui.js
+src/web/public/session-ui.js
+src/web/public/settings-ui.js
+src/web/public/sw.js
+src/web/public/terminal-ui.js
+src/web/public/voice-input.js
+src/web/public/upload.html
+scripts/remotion/
+
+# Hand-maintained; Prettier escapes underscores in glob paths and corrupts paragraphs.
+CLAUDE.md

AGENTS.md

@@ -0,0 +1,16 @@
+# Repository Guidelines
+
+Canonical agent/contributor guidance for this repository lives in [CLAUDE.md](CLAUDE.md) —
+project structure, build/test/lint commands, code style, testing safety rules
+(never run the full suite inside a managed tmux session), security notes, and
+the deployment workflow are all maintained there. Please read it before making
+changes, and keep it the single source of truth rather than duplicating
+sections here.
+
+Quick pointers:
+
+- Type check: `tsc --noEmit` · Lint: `npm run lint` · Format: `npm run format:check`
+- Targeted tests only: `npm test -- test/<file>.test.ts` (bare `npm test` is unsafe in managed sessions)
+- Route tests use `app.inject()`; new tests needing ports must pick a unique `const PORT =`
+- Branch off `master` for all work; Conventional Commit-style messages (`fix(mobile): ...`)
+- Never commit secrets or local state from `~/.codeman/`

CLAUDE.md

@@ -2,23 +2,39 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+> Deep implementation detail lives in [`docs/architecture-invariants.md`](docs/architecture-invariants.md). This file holds the rules that prevent mistakes; that file holds the mechanisms, file inventories, and the history behind each rule. Pointers below are written as `→ architecture-invariants#anchor`. When the goal is raw throughput, [`docs/SPEEDRUN.md`](docs/SPEEDRUN.md) is the fast-execution protocol (it removes ceremony, never the safety rules here).
+>
+> **This file is in `.prettierignore` on purpose.** Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (`agent-*.jsonl` became `agent-\_.jsonl`, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run `prettier --write` on it.
+>
+> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those.
+
 ## Quick Reference
 
-| Task | Command |
-|------|---------|
-| Dev server | `npx tsx src/index.ts web` |
-| Type check | `tsc --noEmit` |
-| Single test | `npx vitest run test/<file>.test.ts` |
-| Production | `npm run build && systemctl --user restart codeman-web` |
+| Task        | Command                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dev server  | `npm run dev` (or `npx tsx src/index.ts web`)                                                                                                                       |
+| Type check  | `tsc --noEmit`                                                                                                                                                      |
+| Lint        | `npm run lint` (fix: `npm run lint:fix`)                                                                                                                            |
+| Format      | `npm run format` (check: `npm run format:check`)                                                                                                                    |
+| Single test | `npm test -- test/<file>.test.ts` (or `npx vitest run --config config/vitest.config.ts test/<file>.test.ts`) — ⚠ **never** run bare `npm test`, see Testing section |
+| Build       | `npm run build` (esbuild via `scripts/build.mjs`, NOT tsc — `tsc --noEmit` is type-check only)                                                                      |
+| Production  | `npm run build && systemctl --user restart codeman-web`                                                                                                             |
 
 ## CRITICAL: Session Safety
 
 **You may be running inside a Codeman-managed tmux session.** Before killing ANY tmux or Claude process:
 
-1. Check: `echo $CODEMAN_TMUX` - if `1`, you're in a managed session
+1. Check: `echo $CODEMAN_MUX` - if `1`, you're in a managed session
 2. **NEVER** run `tmux kill-session`, `pkill tmux`, or `pkill claude` without confirming
 3. Use the web UI or `./scripts/tmux-manager.sh` instead of direct kill commands
 
+**The working tree is shared with other agent sessions.** Several Codeman sessions run against THIS one checkout, so another session can `git checkout` a different branch, or leave half-finished untracked files, while you are mid-task.
+
+- **Always `git branch --show-current` immediately before committing.** Observed 2026-07-27: another session ran `git checkout -b feat/web-tabs`, a commit silently landed there instead of master, and the follow-up `git push origin master` cheerfully reported "Everything up-to-date".
+- To land a commit on master **without** switching branches (which would yank the tree out from under the other session): `git push origin HEAD:master` then `git branch -f master HEAD`. Never `git checkout master` to "fix" it.
+- **Never `git add -A`/`git add .`** — stage explicit paths. A sweep will pick up another session's WIP.
+- Another session's broken WIP can block `npm run build`, since `tsc` is the first step and the build gates on it. That is not your bug to fix. ⚠️ `tsc` still EMITS on type errors, so a failed `npm run build` leaves a rebuilt `dist/index.js` compiled from their tree; check what it pulled in before restarting the service. To deploy frontend-only changes past a blocked `tsc`, run the asset stage of `scripts/build.mjs` (everything after the `tsc`/`chmod` lines is independent of it).
+
 ## CRITICAL: Always Test Before Deploying
 
 **NEVER COM without verifying your changes actually work.** For every fix:
@@ -27,159 +43,129 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM
 
-The production server caches static files for 1 hour (`maxAge: '1h'` in `server.ts`). After deploying frontend changes, users may need a hard refresh (Ctrl+Shift+R) to see updates.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an _absolute_ URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.
 
 ## COM Shorthand (Deployment)
 
-Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`.
+Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`. What SemVer actually covers (the CLI + documented env vars are public; the HTTP/SSE API, on-disk state, and experimental features are internal/unstable) is defined in `docs/versioning-policy.md`. Security reporting + known limitations live in `.github/SECURITY.md`.
 
 When user says "COM":
+
 1. **Determine bump type**: `COM` = patch (default), `COM minor` = minor, `COM major` = major
 2. **Create a changeset file** (no interactive prompts). Write a `.md` file in `.changeset/` with a random filename:
+
    ```bash
    cat > .changeset/$(openssl rand -hex 4).md << 'CHANGESET'
    ---
-   "codeman": patch
+   "aicodeman": patch
    ---
 
-   Description of changes
+   Detailed description of ALL changes since last release (not just the most recent commit — review full git log since last version tag)
    CHANGESET
    ```
-   Replace `patch` with `minor` or `major` as needed. Include `"xterm-zerolag-input": patch` on a separate line if that package changed too.
-3. **Consume the changeset**: `npm run version-packages` (bumps versions in `package.json` files and updates `CHANGELOG.md`)
-4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
-5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.2.1 (must match `package.json`)
+   Replace `patch` with `minor` or `major` as needed. Include `"xterm-zerolag-input": patch` on a separate line if that package changed too.
+
+3. **Consume the changeset**: `npm run version-packages` (auto-bumps `package.json` files, updates `CHANGELOG.md`, runs `npm install --package-lock-only`, and verifies lockfile sync via `scripts/check-lockfile-sync.mjs` — all in one command; never hand-edit `CHANGELOG.md` or `package-lock.json` versions)
+4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
+5. **Commit and deploy**: verify the branch first (`git branch --show-current`), then stage EXPLICIT paths — never `git add -A`, which has swept another session's WIP into a release. `git status --short` and account for every line before committing:
+   `git add <paths> && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
+6. **Wait for CI**: after `git push`, TWO workflows fire per master push — `CI` and `Release` (the npm publish + GitHub release). List both runs for the pushed commit with `gh run list --commit $(git rev-parse HEAD) --json databaseId,workflowName` and watch EACH with `gh run watch <id> --exit-status`. Confirm both pass before considering the release done (`gh run list -L 1` returns only one of the two).
+
+CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
+
+**Version**: 1.8.1 (must match `package.json`)
 
 ## Project Overview
 
 Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs.
 
-**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports both Claude Code and OpenCode AI CLIs via pluggable CLI resolvers.
+**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), and Gemini (Google) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`).
 
-**TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`. Note: `src/tui` is excluded from compilation (legacy/deprecated code path).
+**TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.
 
-**Requirements**: Node.js 18+, Claude CLI, tmux
+**Requirements**: Node.js 22+, Claude CLI, tmux
 
-## Commands
+**Git**: Main branch is `master`. SSH session chooser: `sc` (interactive), `sc 2` (quick attach), `sc -l` (list).
 
-**CRITICAL**: `npm run dev` shows CLI help, NOT the web server.
+## Additional Commands
 
-**Default port**: `3000` (web UI at `http://localhost:3000`)
+`npm run dev` = dev server. Default port: `3000` (override with `--port` or the `CODEMAN_PORT` env var). To run this beta isolated alongside a prod Codeman, use `scripts/run-beta.sh` (sets `CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). Commands not in Quick Reference:
 
-```bash
-# Setup
-npm install                        # Install dependencies
+| Task                           | Command                                                                                                                                                                                                        |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dev with TLS                   | `npx tsx src/index.ts web --https`                                                                                                                                                                             |
+| Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix)                                        |
+| Bind a non-loopback host       | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
+| Continuous typecheck           | `tsc --noEmit --watch`                                                                                                                                                                                         |
+| Watch-mode test                | `npm run test:watch -- test/<file>.test.ts` (always pass a file — bare watch includes the browser suites)                                                                                                      |
+| Test coverage                  | `npm run test:coverage`                                                                                                                                                                                        |
+| Dead-code sweep                | `npm run knip` (config in `config/knip.json`, passed via `--config`)                                                                                                                                          |
+| Rebuild gesture overlay        | `npm run build:gesture` (esbuild `packages/gesture-control/src/codeman/entry.ts` → `src/web/public/gesture/gesture-codeman.js`; commit the result)                                                             |
+| Build the docker agent image   | `node scripts/build-agent-image.mjs` (builds `codeman/agent:base` from `docker/agent.Dockerfile`; prerequisite for Docker cases; `--engine`/`--image`/`--no-cache`)                                            |
+| Gesture playground             | `npm run dev` **in** `packages/gesture-control/` (standalone vite demo, fake tabs)                                                                                                                             |
+| Check public-asset formatting  | `npm run check:public-assets` (prettier-checks `src/web/public/**` text assets; `scripts/check-public-assets.mjs`)                                                                                             |
+| Frontend JS syntax check       | `npm run check:frontend-syntax` (`scripts/check-frontend-syntax.mjs`; runs in CI)                                                                                                                              |
+| CI-equivalent test sweep       | `npm run test:ci` (full suite minus browser/perf — see Testing)                                                                                                                                                |
+| Production start               | `npm run start`                                                                                                                                                                                                |
+| Production logs                | `journalctl --user -u codeman-web -f`                                                                                                                                                                          |
 
-# Development
-npx tsx src/index.ts web           # Dev server (RECOMMENDED)
-npx tsx src/index.ts web --https   # With TLS (only needed for remote access)
-npm run typecheck                  # Type check
-tsc --noEmit --watch               # Continuous type checking
+**CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 3 Playwright tests). Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing).
 
-# Testing (NEVER run full suite from inside Codeman — kills tmux sessions)
-# npx vitest run                   # ALL tests — DANGEROUS inside Codeman
-npx vitest run test/<file>.test.ts # Single file (SAFE)
-npx vitest run -t "pattern"        # Tests matching name
-npm run test:coverage              # With coverage report
+**Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`) — config lives in the **`"prettier"` key of `package.json`**, not a `.prettierrc` (keeps the repo root short; editors read it natively). `.prettierignore` stays at the root because Prettier resolves it relative to cwd. ESLint flat config (`config/eslint.config.js`) allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Ignores: `app.js`, `scripts/**/*.mjs`, `src/web/public/vendor/**`, `scripts/remotion/**`.
 
-# Production
-npm run build
-systemctl --user restart codeman-web
-journalctl --user -u codeman-web -f
-```
+**Prettier scope is deliberately narrow.** `npm run format` globs only `src/**/*.ts` and `src/web/public/**`, and `.prettierignore` then exempts most of `src/web/public/*.js` (app.js, styles.css, index.html, and 14 hand-formatted modules) plus `CLAUDE.md`. Those files are hand-formatted by design; `npm run check:public-assets` and `check:frontend-syntax` are what guard them (NUL bytes + JS syntax), not Prettier. Do not "fix" a file by adding it back to Prettier's scope.
 
 ## Common Gotchas
 
-- **`npm run dev` is NOT the web server** — it shows CLI help. Use `npx tsx src/index.ts web`
-- **Single-line prompts only** — `writeViaMux()` sends text and Enter separately; multi-line breaks Ink
-- **Don't kill tmux sessions blindly** — Check `$CODEMAN_TMUX` first; you might be inside one
-- **Never run full test suite** — `npx vitest run` spawns/kills tmux sessions and will crash your Codeman session. Run individual test files only.
-- **Global regex `lastIndex` sharing** — `ANSI_ESCAPE_PATTERN_FULL/SIMPLE` have `g` flag; use `createAnsiPatternFull/Simple()` factory functions for fresh instances in loops
-- **DEC 2026 sync blocks** — Never discard incomplete sync blocks (START without END); buffer up to 50ms then flush. See `app.js:extractSyncSegments()`
-- **Terminal writes during buffer load** — Live SSE writes are queued while `_isLoadingBuffer` is true to prevent interleaving with historical data
-- **Local echo prompt scanning** — Does NOT use `buffer.cursorY` (Ink moves it); scans buffer bottom-up for visible `>` prompt marker
+- **Single-line prompts only** — `writeViaMux()` sends text+Enter separately; multi-line breaks Ink
+- **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
+- **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly. Both `aicodeman` and `codeman` bin aliases are installed (`package.json` `bin`)
+- **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.)
+- **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
+- **Model choice flows via `settings.local.json`, NOT `--model` or env** — the App Settings **Claude Model** picker (`claudeModel` in `settings.json`) is read by `session-ui.js` at session create (wins over the legacy 1M-Opus toggles `opusContext1m`/`opusContext1mEnabled`), sent as the `modelOverride` payload field, and `updateCaseModel()` (`hooks-config.ts`) writes/deletes the `model` key in `<case>/.claude/settings.local.json`. This is the intended exception to the envOverrides rule above: model legitimately lives in `settings.local.json` (a soft default — in-session `/model` still works); env vars do not
+- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. Resolver design pattern: `docs/opencode-integration.md`
+- **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. This has caused real shipped bugs twice
+- **`xterm-zerolag-input` is single-source** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/`, and is bundled into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` (dev, by `scripts/postinstall.js`) and `dist/.../vendor/` (prod, by `scripts/build.mjs`). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundle.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
+- **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
+- **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
+- **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)
 
-## Import Conventions
-
-- **Utilities**: Import from `./utils` (re-exports all): `import { LRUMap, stripAnsi } from './utils'`
-- **Types**: Use type imports: `import type { SessionState } from './types'`
-- **Config**: Import from specific files: `import { MAX_TERMINAL_BUFFER_SIZE } from './config/buffer-limits'`
+**Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
 
 ## Architecture
 
-### Core Files
+### Core Files (by domain)
 
-| File | Purpose |
-|------|---------|
-| `src/session.ts` | PTY wrapper: `runPrompt()`, `startInteractive()`, `startShell()` |
-| `src/mux-interface.ts` | `TerminalMultiplexer` interface + `MuxSession` type |
-| `src/mux-factory.ts` | Create tmux multiplexer instance |
-| `src/tmux-manager.ts` | tmux session management |
-| `src/session-manager.ts` | Session lifecycle, cleanup |
-| `src/state-store.ts` | State persistence to `~/.codeman/state.json` |
-| `src/respawn-controller.ts` | State machine for autonomous cycling |
-| `src/ralph-tracker.ts` | Detects `<promise>PHRASE</promise>`, todos |
-| `src/ralph-loop.ts` | Autonomous task execution loop (polls queue, assigns tasks) |
-| `src/ralph-config.ts` | Parses `.claude/ralph-loop.local.md` plugin config |
-| `src/task.ts` | Task model for prompt execution |
-| `src/task-queue.ts` | Priority queue for tasks with dependencies |
-| `src/task-tracker.ts` | Background task tracker for subagent detection |
-| `src/subagent-watcher.ts` | Monitors Claude Code's Task tool (background agents) |
-| `src/team-watcher.ts` | Polls `~/.claude/teams/` for agent team activity; matches teams to sessions via `leadSessionId` |
-| `src/run-summary.ts` | Timeline events for "what happened while away" |
-| `src/ai-checker-base.ts` | Base class for AI-powered checkers (shared by idle + plan checkers) |
-| `src/ai-idle-checker.ts` | AI-powered idle detection |
-| `src/ai-plan-checker.ts` | AI-powered plan completion checker |
-| `src/bash-tool-parser.ts` | Parses Claude's bash tool invocations from output |
-| `src/transcript-watcher.ts` | Watches Claude's transcript files for changes |
-| `src/hooks-config.ts` | Manages `.claude/settings.local.json` hook configuration |
-| `src/push-store.ts` | VAPID key auto-gen + push subscription CRUD for Web Push |
-| `src/session-lifecycle-log.ts` | Append-only JSONL audit log at `~/.codeman/session-lifecycle.jsonl` |
-| `src/image-watcher.ts` | Watches for image file creation (screenshots, etc.) |
-| `src/file-stream-manager.ts` | Manages `tail -f` processes for live log viewing |
-| `src/plan-orchestrator.ts` | Multi-agent plan generation with research and planning phases |
-| `src/prompts/index.ts` | Barrel export for all agent prompts |
-| `src/prompts/*.ts` | Agent prompts (research-agent, planner) |
-| `src/templates/claude-md.ts` | CLAUDE.md generation for new cases |
-| `src/cli.ts` | Command-line interface handlers |
-| `src/web/server.ts` | Fastify REST API + SSE at `/api/events` (~105 routes) |
-| `src/web/schemas.ts` | Zod v4 validation schemas with path/env security allowlists |
-| `src/web/public/app.js` | Frontend: xterm.js, tab management, subagent windows, mobile support (~17K lines) |
-| `src/types.ts` | All TypeScript interfaces (~70 type/interface/enum defs, ~1450 lines) |
+| Domain           | Key files                                                                                              | Notes                                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Entry**        | `src/index.ts`, `src/cli.ts`                                                                           |                                                                                                  |
+| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
+| **Mux**          | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★                                  |                                                                                                  |
+| **Respawn**      | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`)      | Read `docs/respawn-state-machine.md` first                                                       |
+| **Ralph**        | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first                                                          |
+| **Orchestrator** | `src/orchestrator-loop.ts`, `-planner`, `-verifier`                                                    | Read `docs/orchestrator-loop-architecture.md` first                                              |
+| **Cron**         | `src/cron/cron-service.ts`, `cron-time.ts` (pure next-run math), `cron-input.ts`                        | Read `docs/cron-discovery.md` first. Distinct from legacy `ScheduledRun` (`/api/scheduled`)      |
+| **Agents**       | `src/subagent-watcher.ts` ★, `team-watcher`, `bash-tool-parser`, `transcript-watcher`, `workflow-run-watcher` | `workflow-run-watcher` is STANDALONE and never touches `subagent-watcher`                        |
+| **AI**           | `src/ai-checker-base.ts`, `ai-idle-checker.ts`, `ai-plan-checker.ts`                                   |                                                                                                  |
+| **Tasks**        | `src/task.ts`, `task-queue.ts`, `task-tracker.ts`                                                      |                                                                                                  |
+| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`                                     |                                                                                                  |
+| **Infra**        | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` (pure), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns                                                    |
+| **Search**       | `src/search-service.ts`                                                                                | Pure in-memory core for `GET /api/search`                                                        |
+| **Attachments**  | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns                                                                                 |
+| **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases                                |
+| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (20 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
+| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 23 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
+| **Types**        | `src/types/index.ts` (barrel) → 19 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
 
-**Large files** (>50KB): `app.js`, `ralph-tracker.ts`, `respawn-controller.ts`, `session.ts`, `subagent-watcher.ts` — these contain complex state machines; read `docs/respawn-state-machine.md` before modifying.
+★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
 
-### Local Packages
+**Local packages**: `packages/xterm-zerolag-input/` (local echo overlay, single-source, see Gotchas). `packages/gesture-control/` (`codeman-gesture-control`, hand-tracking overlay source, built via `npm run build:gesture`).
 
-| Package | Purpose |
-|---------|---------|
-| `packages/xterm-zerolag-input/` | Instant keystroke feedback overlay for xterm.js — eliminates perceived input latency over high-RTT connections. Source of truth for `LocalEchoOverlay`; a copy is embedded in `app.js`. Build: `npm run build` (tsup). |
+**Config**: `src/config/` — 16 files, no barrel (`index.ts`) exists; import from the specific file.
 
-### Config Files (`src/config/`)
-
-| File | Purpose |
-|------|---------|
-| `buffer-limits.ts` | Terminal/text buffer size limits |
-| `map-limits.ts` | Global limits for Maps, sessions, watchers |
-
-### Utility Files (`src/utils/`)
-
-| File | Purpose |
-|------|---------|
-| `index.ts` | Re-exports all utilities (standard import point) |
-| `lru-map.ts` | LRU eviction Map for bounded caches |
-| `nice-wrapper.ts` | Wrap commands with `nice` priority adjustment |
-| `stale-expiration-map.ts` | TTL-based Map with lazy expiration |
-| `claude-cli-resolver.ts` | Resolve Claude CLI binary across install paths |
-| `cleanup-manager.ts` | Centralized resource disposal |
-| `buffer-accumulator.ts` | Chunk accumulator with size limits |
-| `string-similarity.ts` | String matching utilities (fuzzy matching) |
-| `token-validation.ts` | Token count parsing and validation |
-| `regex-patterns.ts` | Shared regex patterns for parsing |
-| `type-safety.ts` | `assertNever()` for exhaustive switch/case type checking |
-| `opencode-cli-resolver.ts` | Resolve OpenCode CLI binary across install paths |
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
 
 ### Data Flow
 
@@ -190,371 +176,177 @@ journalctl --user -u codeman-web -f
 
 ### Key Patterns
 
-**Input to sessions**: Use `session.writeViaMux()` for programmatic input (respawn, auto-compact). Uses tmux `send-keys -l` (literal text) + `send-keys Enter`. All prompts must be single-line.
-
-**Terminal multiplexer**: `TerminalMultiplexer` interface (`src/mux-interface.ts`) abstracts the backend. `createMultiplexer()` from `src/mux-factory.ts` creates the tmux backend.
+**Input**: `session.writeViaMux()` for programmatic/curl input via tmux `send-keys -l` + `send-keys Enter`, single-line only. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
-**Token tracking**: Interactive mode parses status line ("123.4k tokens"), estimates 60/40 input/output split.
+**Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit)
 
-**Hook events**: Claude Code hooks trigger notifications via `/api/hook-event`. Key events: `permission_prompt` (tool approval needed), `elicitation_dialog` (Claude asking question), `idle_prompt` (waiting for input), `stop` (response complete), `teammate_idle` (Agent Teams), `task_completed` (Agent Teams). See `src/hooks-config.ts`.
+**Plan-usage chip** (statusLine telemetry, opt-in `showPlanUsageLimits`, default OFF): Codeman injects its own `statusLine.command` exporter which POSTs Claude's `rate_limits` blob to `POST /api/status-telemetry`. The exporter is identified by a marker, so it only ever adds/updates/removes a statusLine that is **ours**, never a user's hand-authored one, and it prints the footer through so the in-terminal statusline is not blanked. Claude-mode only; distinct from auto-resume, which reacts to the limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
 
-**Web Push**: Layer 5 of the notification system. Service worker (`sw.js`) receives push events and shows OS-level notifications even when the browser tab is closed. VAPID keys auto-generated on first use and persisted to `~/.codeman/push-keys.json`. Per-subscription per-event preferences stored in `~/.codeman/push-subscriptions.json`. Expired subscriptions (410/404) auto-cleaned. Requires HTTPS or localhost. iOS requires PWA installed to home screen. See `src/push-store.ts`.
+**Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
 
-**Agent Teams (experimental)**: `TeamWatcher` polls `~/.claude/teams/` for team configs and matches teams to sessions via `leadSessionId`. Teammates are in-process threads (not separate OS processes) and appear as standard subagents. RespawnController checks `TeamWatcher.hasActiveTeammates()` before triggering respawn. Enable via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var in `settings.local.json`. See `agent-teams/` for full docs.
+**Cron (`CronJob`s)**: saved, named jobs on a recurring schedule (`once`/`interval`/`daily`/`weekly`) with per-job run history. ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded loop); the two never interact and keep separate `Scheduled*` / `Cron*` names. `CronService` **reuses the existing session layer** rather than rebuilding tmux logic. Next-run math is pure and unit-tested in `cron-time.ts` (server-local timezone). The schedule is advanced BEFORE launch so a slow launch cannot re-trigger. → [architecture-invariants#cron-jobs](docs/architecture-invariants.md#cron-jobs), `docs/cron-discovery.md`
 
-**Circuit breaker**: Prevents respawn thrashing when Claude is stuck. States: `CLOSED` (normal) → `HALF_OPEN` (testing) → `OPEN` (blocked). Tracks consecutive no-progress, same-error-repeated, and tests-failing-too-long. Reset via API at `/api/sessions/:id/ralph-circuit-breaker/reset`.
+**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md`
 
-**Respawn cycle metrics & health scoring**: `RespawnCycleMetrics` tracks per-cycle outcomes (success, stuck_recovery, blocked, error). `RalphLoopHealthScore` computes 0-100 health with component scores (cycleSuccess, circuitBreaker, iterationProgress, aiChecker, stuckRecovery). Available via respawn status API.
+**Docker cases**: a case can point at a **container**, with any of the five CLI backends running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
 
-**Subagent-session correlation**: Session parses Task tool output via `BashToolParser` → `SubagentWatcher` discovers new agent → calls `session.findTaskDescriptionNear()` to match description for window title.
+**External CLI modes (OpenCode, Codex, Gemini)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All three **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. → [architecture-invariants#external-cli-modes-opencode-codex-gemini](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini)
 
-### Frontend Files
+**Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
 
-| File | Purpose |
-|------|---------|
-| `src/web/public/index.html` | HTML entry point with inline critical CSS and async vendor loading |
-| `src/web/public/app.js` | Core UI: xterm.js, tab management, subagent windows, mobile support (~17.5K lines) |
-| `src/web/public/styles.css` | Main styling (dark theme, layout, components) |
-| `src/web/public/mobile.css` | Responsive overrides for screens <1024px (loaded conditionally via `media` attribute) |
-| `src/web/public/upload.html` | Screenshot upload page served at `/upload.html` |
-| `src/web/public/sw.js` | Service worker for Web Push notifications |
-| `src/web/public/manifest.json` | Minimal PWA manifest (required for push on Android) |
-| `src/web/public/vendor/` | Self-hosted xterm.js + addons (eliminates CDN latency) |
+**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
 
-### Frontend Architecture (`app.js`)
+**Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`.
 
-The frontend is a single ~17.5K-line vanilla JS file with these key systems:
+**Agent Teams**: `TeamWatcher` polls `~/.claude/teams/`, matches to sessions via `leadSessionId`. Teammates are in-process threads appearing as subagents. Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. See `docs/agent-teams/`.
 
-| System | Key Classes/Functions | Purpose |
-|--------|----------------------|---------|
-| **Terminal rendering** | `batchTerminalWrite()`, `flushPendingWrites()`, `chunkedTerminalWrite()` | 60fps batched writes with DEC 2026 sync |
-| **Local echo overlay** | `LocalEchoOverlay` class | DOM overlay for instant mobile keystroke feedback |
-| **Mobile support** | `MobileDetection`, `KeyboardHandler`, `SwipeHandler`, `KeyboardAccessoryBar` | Touch input, viewport adaptation, swipe navigation |
-| **Subagent windows** | `openSubagentWindow()`, `closeSubagentWindow()`, `updateConnectionLines()` | Floating terminal windows with parent connection lines |
-| **Notifications** | `NotificationManager` class | 5-layer: in-app drawer, tab flash, browser API, web push, audio beep |
-| **SSE connection** | `connectSSE()`, `addListener()` | EventSource with exponential backoff (1-30s), offline queue (64KB) |
-| **Settings** | `openAppSettings()`, `apply*Visibility()` | Server-backed + localStorage persistence |
-| **Focus management** | `FocusTrap` class | Modal keyboard navigation with focus restore |
+**Circuit breakers**: the Ralph breaker prevents respawn thrashing (`CLOSED` → `HALF_OPEN` → `OPEN`; reset via `/api/sessions/:id/ralph-circuit-breaker/reset`). **Distinct: the PTY-exit breaker** (`session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits and blocks auto-restarts. ⚠️ It resets ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive`; the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. → [architecture-invariants#circuit-breakers-ralph--pty-exit](docs/architecture-invariants.md#circuit-breakers-ralph-and-pty-exit)
 
-**Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).
+**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. Only the FIRST buffer load after a page load requests `full=1`; tab switches keep the cheap `?tail=` path. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
 
-**Built-in respawn presets**: `solo-work` (3s idle, 60min), `subagent-workflow` (45s idle, 240min), `team-lead` (90s idle, 480min), `ralph-todo` (8s idle, 480min, works through @fix_plan.md tasks), `overnight-autonomous` (10s idle, 480min, full reset).
+**Self-update** (App Settings → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
 
-**Keyboard shortcuts**: Escape (close panels), Ctrl+? (help), Ctrl+Enter (quick start), Ctrl+W (kill session), Ctrl+Tab (next session), Ctrl+K (kill all), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl/Cmd +/- (font size).
+**Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments)
+
+**Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
+
+**Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
+
+**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
+
+**Away digest**: `GET /api/away-digest` aggregates what happened while you were away from the lifecycle log, run-summary events, live sessions, token stats, and recent subagents. Pure aggregator in `web/away-digest.ts`. ⚠️ Returns `{success:true,digest}`, a legacy raw-ish shape consistent with the other raw GET handlers in `system-routes.ts`; frontend and tests read `.digest`. → [architecture-invariants#away-digest](docs/architecture-invariants.md#away-digest)
+
+**Ralph todo-config**: per-session `maxTodos` (FIFO-eviction cap, default 500 = `MAX_TODOS_PER_SESSION`) + `todoExpirationMinutes` (auto-expiry, default 60) set via `POST /api/sessions/:id/ralph-config` (`RalphConfigSchema`, both `.int().positive()`). Stored on the tracker (`setMaxTodos`/`setTodoExpirationMinutes`) and **persisted/read-back via `RalphTrackerState`** (surfaced in the `loopState` getter → `toState()` + SSE broadcast → modal `populateRalphForm`), mirroring how `maxIterations` round-trips. Claude-only (skipped by `isExternalCliMode`).
+
+**Port interfaces**: Routes declare dependencies via port interfaces (`src/web/ports/`). Routes use intersection types (e.g., `SessionPort & EventPort`).
+
+### Frontend
+
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
+
+**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)
+
+**Per-device vs synced settings**: the `displayKeys` set in settings-ui.js is a **client-side merge policy**, not a wire filter. A display key seeds from the server only when localStorage has no value for it, which is what prevents one device overwriting another; `showPlanUsageLimits` is additionally `delete`d from the incoming payload outright. Separately, `SettingsUpdateSchema` is `.strict()` and simply **does not declare** `skin`, `showFileViewerButton`, `showCronButton`, `webglRendererEnabled`, `localEchoEnabled`, `cjkInputEnabled`, or `extendedKeyboardBar`, so sending one of those is a validation error. The rest (`showResponseViewer`, `showPlanUsageLimits`, `language`, and most `show*` keys) ARE in the schema and do persist server-side; they are per-device by client policy only. ⚠️ Adding a new per-device setting means deciding **both** questions: membership in `displayKeys`, and presence in the schema.
+
+**Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
+
+**Gesture control** (camera hand-tracking overlay, opt-in, default OFF): `CODEMAN_GESTURE=1` makes the feature *available*; `gestureControlEnabled` turns it on. The bundle is injected by `renderIndexHtml` only when enabled, which is why that method is `async` and reads settings with `readSettings(true)` (a fresh read: a post-save reload lands inside the 2s cache TTL and would otherwise render the pre-toggle state). **Source lives in `packages/gesture-control/`; edit there, run `npm run build:gesture`, and commit the regenerated bundle** because dev serves the committed bundle with no runtime bundler. The MediaPipe wasm + model are fetched separately and gitignored. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision`. → [architecture-invariants#gesture-control-the-source-package](docs/architecture-invariants.md#gesture-control-the-source-package)
+
+**Theme skins / branding / i18n**: `skin` selects a palette via `data-skin` on `<html>`, applied by an **inline pre-paint script** in `index.html` reading `localStorage['codeman:skin']` to avoid a flash of wrong theme. `displayName` changes user-facing browser branding only and must NEVER rename npm package, CLI, API, storage, CSS, or protocol identifiers. `language` (`en`/`zh-CN`) keeps English as the canonical source so live switching stays reversible. User display names flow through `textContent`/attribute APIs and the server title's HTML escaper, never `innerHTML`. → [architecture-invariants#theme-skins](docs/architecture-invariants.md#theme-skins)
+
+**Foldable settings identity**: responsive layout is width-driven via `MobileDetection.getDeviceType()`, but the localStorage namespace uses `MobileDetection.isHandheldDevice()` so an unfolded Android foldable keeps `codeman-app-settings-mobile`. ⚠️ Do not switch per-device settings namespaces from instantaneous viewport width: a posture-triggered WebView reload would lose opt-in UI. Regression profile: `OPPO Find N5 (unfolded)` in `test/mobile/devices.ts`. → [architecture-invariants#foldable-settings-identity](docs/architecture-invariants.md#foldable-settings-identity)
+
+**WebGL renderer toggle** (`webglRendererEnabled`, per-device): the GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads and is cleared only by an explicit OFF→ON save or `?webgl=force`. `?nowebgl` forces the DOM renderer per-load. → [architecture-invariants#webgl-renderer-toggle](docs/architecture-invariants.md#webgl-renderer-toggle)
+
+**Phone toolbar: Enter replaces Shell** (post-1.8.0): inside `@media (max-width: 430px)` `btn-shell` is `display:none` and `btn-enter` takes its slot (`order: 4`); starting a shell moved into the Run dropdown (`Terminal / Shell` → `setRunMode('shell')` → `run()` → `runShell()`, button label "Run SH"). `runMode` is `z.string().max(20)` server-side, so new modes need no schema change. Desktop and tablet keep the green Run Shell button unchanged.
+
+⚠️ **`sendEnterKey()` MUST go through `terminal._core.coreService.triggerDataEvent('\r', true)`** — not `sendInput()`, and never a raw POST to `/api/sessions/:id/input`. `localEchoEnabled` defaults to `MobileDetection.isTouchDevice()`, so on every phone the characters you type are buffered in the `LocalEchoOverlay` and have **never reached the PTY**; the `onData` Enter branch in terminal-ui.js is what flushes `pendingText` first and only then sends `\r` (after an 80ms delay so text lands first). Sending a bare `\r` submits an empty line and strands the typed text on screen, so the button looks dead. Replaying the keypress reuses the overlay flush, the flushed-offset cleanup and the ordering instead of reimplementing them. `KeyboardAccessory.sendKey()` is for escape sequences (arrows/Esc) and is the WRONG template to copy for input.
+
+⚠️ **Skin overrides outrank plain class rules.** `styles.css` nests its skin block inside `html:not([data-skin="og"]) { … }`, so a bare `.btn-toolbar` rule in there resolves to specificity **(0,2,1)** and beats a `.btn-toolbar.btn-x` rule **(0,2,0)** in `mobile.css` regardless of load order. Toolbar-button colors set from mobile.css therefore need `!important` — that is why mobile.css leans on it so heavily. Symptom: only your `!important` properties land and everything else silently renders in generic toolbar grey.
+
+**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried), log viewers (2000), image popups (3000), local echo overlay (7).
+
+**Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).
+
+**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry.
 
 ### Security
 
-- **HTTP Basic Auth**: Optional via `CODEMAN_USERNAME`/`CODEMAN_PASSWORD` env vars
-- **Session cookies**: After Basic Auth, a 24h session cookie (`codeman_session`) is issued so credentials aren't re-sent on every request. Active sessions auto-extend. SSE works via same-origin cookie (`EventSource` can't send custom headers).
-- **Rate limiting**: 10 failed auth attempts per IP triggers 429 rejection (15-minute decay window). Manual `StaleExpirationMap` counter — no `@fastify/rate-limit` needed.
-- **Hook bypass**: `/api/hook-event` POST is exempt from auth — Claude Code hooks curl this from localhost and can't present credentials. Safe: validated by `HookEventSchema`, only triggers broadcasts.
-- **CORS**: Restricted to localhost only
-- **Security headers**: X-Content-Type-Options, X-Frame-Options, CSP; HSTS if HTTPS
-- **Path validation** (`schemas.ts`): Strict allowlist regex, no shell metacharacters, no traversal, must be absolute
-- **Env var allowlist**: Only `CLAUDE_CODE_*` prefixes allowed; blocks `PATH`, `LD_PRELOAD`, `NODE_OPTIONS`, `CODEMAN_*` keys
-- **File streaming TOCTOU protection**: `FileStreamManager` calls `realpathSync()` twice (at validation and before spawn) to catch symlink swaps
+**Full model: [`docs/security-architecture.md`](docs/security-architecture.md)** (network binding, auth pipeline, the tunnel caveat, file-serving hardening, supply-chain, instance isolation, recommended setups). **Layer-by-layer detail with the history behind each: [architecture-invariants#security-layers](docs/architecture-invariants.md#security-layers).**
 
-### SSE Event Categories
+| Layer             | The rule                                                                                                                                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auth**          | Optional HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`)                                                        |
+| **Network bind**  | Defaults to loopback. Non-loopback without a password starts but warns loudly. Classifier: `network-auth-policy.ts`                                                                                          |
+| **Host guard**    | Always-on Host-header allowlist blocking DNS rebinding. ⚠️ **Custom reverse-proxy domains are rejected** unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`                                              |
+| **CSRF / Origin** | Always-on cross-site Origin guard on state-changing requests. **A missing Origin is allowed** so curl/CLI and hooks keep working. ⚠️ The body parser keeps `text/plain` RAW; auto-JSON-parsing it enabled simple-request CSRF |
+| **QR Auth**       | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md`                                                                                                                              |
+| **Sessions**      | 24h cookie (`codeman_session`), auto-extend, device context audit                                                                                                                                           |
+| **Rate limit**    | 10 failed auth/IP → 429 (15min decay). QR and hook-secret have separate buckets, so neither can lock out login                                                                                              |
+| **Hook bypass**   | `/api/hook-event` + `/api/status-telemetry` skip Basic auth (localhost-only, schema-validated), but when auth is active the loopback bypass requires `X-Codeman-Hook-Secret` **unconditionally** (Codeman cannot detect a user's own loopback reverse proxy) |
+| **Tunnel**        | Enabling a tunnel **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` or the per-request `acknowledgeUnauthTunnel:true` action field (never persisted) |
+| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`)                                                                        |
+| **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                     |
 
-~80+ event types broadcast via `broadcast()`. Key categories:
+**Security-relevant env vars**: `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS=1` (opt-in hooks-only listener on the docker bridge gateway).
 
-| Category | Events | Purpose |
-|----------|--------|---------|
-| Session | `session:created/updated/deleted/working/idle/exit/error/completion` | Lifecycle |
-| Terminal | `session:terminal`, `session:clearTerminal`, `session:needsRefresh` | Output streaming |
-| Respawn | `respawn:stateChanged/cycleStarted/blocked/aiCheck*/planCheck*/timer*` | Respawn state machine |
-| Subagent | `subagent:discovered/updated/completed/tool_call/progress` | Background agents |
-| Ralph | `session:ralphLoopUpdate/ralphTodoUpdate/ralphCompletionDetected` | Ralph tracking |
-| Hooks | `hook:{eventName}` (dynamic) | Claude Code hook events |
-| Plan | `plan:started/progress/completed/cancelled/subagent` | Plan orchestration |
-| Mux | `mux:created/killed/died/statsUpdated` | tmux process monitor |
-| Image | `image:detected` | Screenshot detection |
+### SSE Event Registry
 
-### API Route Categories
+148 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync** — they are currently exactly in sync, and the backend file's `@fileoverview` carries the per-category breakdown.
 
-~105 routes in `server.ts:buildServer()`. Key groups:
+### API Routes
 
-| Group | Prefix | Count | Key endpoints |
-|-------|--------|-------|---------------|
-| Sessions | `/api/sessions` | ~20 | CRUD, input, resize, interactive, shell |
-| Respawn | `/api/sessions/:id/respawn` | 5 | start, stop, enable, config |
-| Ralph | `/api/sessions/:id/ralph-*` | 6 | state, status, config, circuit-breaker |
-| Plan | `/api/sessions/:id/plan/*` | 5 | task CRUD, checkpoint, history, rollback |
-| Subagents | `/api/subagents` | 7 | list, transcript, kill, cleanup |
-| Cases | `/api/cases` | 5 | CRUD, link, fix-plan |
-| Scheduled | `/api/scheduled` | 4 | CRUD for scheduled runs |
-| Push | `/api/push` | 4 | VAPID key, subscribe, update prefs, unsubscribe |
-| System | `/api/status`, `/api/stats`, `/api/config`, `/api/settings` | 8 | App state, config |
-| Files | `/api/sessions/:id/file*`, `tail-file` | 5 | Browser, preview, raw, tail stream |
-| Mux | `/api/mux-sessions` | 4 | tmux management, stats |
+~190 handlers across 20 route files in `src/web/routes/`: system (45), sessions (32), cases (27), files (14), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), me (2), teams (2), search (1), hooks (1), clipboard (1), status-telemetry (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+
+**HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 
 ## Adding Features
 
-- **API endpoint**: Types in `types.ts`, route in `server.ts:buildServer()`, use `createErrorResponse()`. Validate request bodies with Zod schemas in `schemas.ts`.
-- **SSE event**: Emit via `broadcast()`, handle in `app.js` SSE listener section (search `addListener(`)
-- **Session setting**: Add to `SessionState` in `types.ts`, include in `session.toState()`, call `persistSessionState()`
-- **Hook event**: Add to `HookEventType` in `types.ts`, add hook command in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema` in `schemas.ts`
-- **Mobile feature**: Add to relevant mobile singleton (`KeyboardHandler`, `KeyboardAccessoryBar`, etc.), test with `MobileDetection.isMobile()` guard
-- **New test**: Pick unique port (search `const PORT =`), add port comment to test file header. Tests use ports 3150+.
+- **API endpoint**: Types in `src/types/` domain file, route in `src/web/routes/*-routes.ts`. Return the `ApiResponse` envelope (`{ success: true, data }`; errors via `createErrorResponse()` with proper status code). Validate with Zod schemas in `schemas.ts`.
+- **SSE event**: Add to `src/web/sse-events.ts` + `SSE_EVENTS` in `constants.js`, emit via `broadcast()`, handle in `app.js` (`addListener(`)
+- **Session setting**: Add to `SessionState`, include in `session.toState()`, call `persistSessionState()`
+- **App setting**: decide per-device vs synced first. Per-device keys go in the `displayKeys` set in settings-ui.js and must NOT be added to `SettingsUpdateSchema` (it is `.strict()`).
+- **Hook event**: Add to `HookEventType`, add hook in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema`
+- **Mobile feature**: Add to relevant singleton, guard with `MobileDetection.isMobile()`. New header buttons must stay off phones (`test/mobile-header-buttons-policy.test.ts`).
+- **New test**: Pick unique port (search `const PORT =`). Route tests use `app.inject()` (no port needed) — see `test/routes/_route-test-utils.ts`.
 
-**Validation**: Uses Zod v4 for request validation. Define schemas in `schemas.ts` and use `.parse()` or `.safeParse()`. Note: Zod v4 has different API from v3 (e.g., `z.object()` options changed, error formatting differs).
+**Validation**: Zod v4 (different API from v3). Define schemas in `schemas.ts`, use `.parse()`/`.safeParse()`.
 
 ## State Files
 
-| File | Purpose |
-|------|---------|
-| `~/.codeman/state.json` | Sessions, settings, tokens, respawn config |
-| `~/.codeman/mux-sessions.json` | Tmux session metadata for recovery |
-| `~/.codeman/settings.json` | User preferences |
-| `~/.codeman/push-keys.json` | VAPID key pair for Web Push (auto-generated) |
-| `~/.codeman/push-subscriptions.json` | Registered push notification subscriptions |
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json`, `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
-## Default Settings
-
-UI defaults are set in `src/web/public/app.js` using `??` fallbacks. To change defaults, edit `openAppSettings()` and `apply*Visibility()` functions.
-
-**Key defaults:** Most panels hidden (monitor, subagents shown), notifications enabled (audio disabled), subagent tracking on, Ralph tracking off.
+**Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 
 ## Testing
 
-**CRITICAL: You are running inside a Codeman-managed tmux session.** Never run `npx vitest run` (full suite) — it spawns/kills tmux sessions and will crash your own session. Instead:
+**Never run the bare full suite** (`npm test` with no file argument): the default config includes the browser-driven suites (`test/mobile/**` and 3 other Playwright tests), which need a live server + chromium + environment-specific PNG baselines and will fail/hang locally. Run individual files, or `test:ci` for a broad sweep:
 
 ```bash
-# Safe: run individual test files
-npx vitest run test/<specific-file>.test.ts
-
-# Safe: run tests matching a pattern
-npx vitest run -t "pattern"
-
-# DANGEROUS from inside Codeman — will kill your tmux session:
-# npx vitest run          ← DON'T DO THIS
+npm test -- test/<specific-file>.test.ts         # Single file (SAFE, uses config/vitest.config.ts)
+npm test -- -t "pattern"                          # By name (SAFE)
+npm run test:ci                                   # Everything except browser/perf suites — what CI runs
+# npm test                                        # DON'T — includes browser/visual suites
 ```
 
-**Ports**: Unit tests pick unique ports manually. Search `const PORT =` before adding new tests.
+Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pass `--config config/vitest.config.ts`.
 
-**Config**: Vitest with `globals: true`, `fileParallelism: false`. Unit timeout 30s.
+**Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s. `config/vitest.ci.config.ts` = same minus the browser/perf excludes — keep the two configs in sync when changing shared options.
 
-**Safety**: `test/setup.ts` snapshots pre-existing tmux sessions at load time and never kills them. Only sessions registered via `registerTestTmuxSession()` get cleaned up.
+**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). Every docker IO path is no-op'd the same way. `test/setup.ts` additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions).
 
-**Respawn tests**: Use MockSession from `test/respawn-test-utils.ts` to avoid spawning real Claude processes.
+**Ports**: Pick unique ports manually, 3150+. Search `const PORT =` before adding new tests. Never 3000 (the live instance).
 
-**Mobile tests**: Separate Playwright-based suite in `mobile-test/` with 135 device profiles. Run via `npx vitest run --config mobile-test/vitest.config.ts`. See `mobile-test/README.md`.
+⚠️ **Browser tests can pass vacuously on mobile input paths.** Two traps, both hit on 2026-07-27 while fixing the phone Enter button: **(1)** driving input with `app.sendInput('…')` writes PAST the `LocalEchoOverlay`, so `pendingText` stays empty and any overlay bug is invisible — type with `page.keyboard.type()` instead; **(2)** headless Chromium reports `MobileDetection.isTouchDevice()` **false even with `hasTouch: true`**, so `_localEchoEnabled` is off and the local-echo branch never executes. Force it (`app._localEchoEnabled = true`) or the test proves nothing. Assert on real state (`app._localEchoOverlay.pendingText`, plus `tmux -L codeman capture-pane -p -t <pane>` for what actually reached the PTY), not on HTTP 200.
 
-## Screenshots ("sc")
+**Testing against the live instance**: prod is HTTPS-only on :3000 (`curl -sk https://localhost:3000/...`). ⚠️ `w1`/`w2`/`w3` are the user's REAL sessions — never send input to them. Create your own throwaway session (`POST /api/sessions` then `POST /api/sessions/:id/shell`; creation alone leaves `pid: null` and no pane), test against that, and `DELETE` it by exact id when done.
 
-When the user says "check the sc", "screenshot", or "sc", they mean uploaded screenshots from their mobile device. Screenshots are saved to `~/.codeman/screenshots/` and uploaded via `/upload.html` on the Codeman web UI. To view them, use the Read tool on the image files:
-
-```bash
-ls ~/.codeman/screenshots/        # List uploaded screenshots
-# Then use Read tool on individual files — Claude Code can view images natively
-```
-
-API: `GET /api/screenshots` (list), `GET /api/screenshots/:name` (serve), `POST /api/screenshots` (upload multipart/form-data). Source: `src/web/public/upload.html`.
+**Respawn tests**: Use `MockSession` from `test/mocks/index.ts` (defined in `test/mocks/mock-session.ts`). **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (136 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
 
 ## Debugging
 
 ```bash
-tmux list-sessions                  # List tmux sessions
-tmux attach-session -t <name>       # Attach (Ctrl+B D to detach)
-curl localhost:3000/api/sessions    # Check sessions
-curl localhost:3000/api/status | jq # Full app state
-cat ~/.codeman/state.json | jq    # View persisted state
-curl localhost:3000/api/subagents   # List background agents
-curl localhost:3000/api/sessions/:id/run-summary | jq  # Session timeline
+tmux list-sessions                                 # List tmux sessions
+curl localhost:3000/api/sessions | jq              # Check sessions
+curl localhost:3000/api/status | jq                # Full app state
+curl localhost:3000/api/subagents | jq             # Background agents
+cat ~/.codeman/state.json | jq                     # Persisted state
 ```
 
-## Troubleshooting
+Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/screenshots`.
 
-| Problem | Check | Fix |
-|---------|-------|-----|
-| Session won't start | `tmux list-sessions` for orphans | Kill orphaned sessions, check Claude CLI installed |
-| Port 3000 in use | `lsof -i :3000` | Kill conflicting process or use `--port` flag |
-| SSE not connecting | Browser console for errors | Check CORS, ensure server running |
-| Respawn not triggering | Session settings → Respawn enabled? | Enable respawn, check idle timeout config |
-| Terminal blank on tab switch | Network tab for `/api/sessions/:id/buffer` | Check session exists, restart server |
-| Tests failing on session limits | `tmux list-sessions \| wc -l` | Clean up: `tmux list-sessions \| grep test \| awk -F: '{print $1}' \| xargs -I{} tmux kill-session -t {}` |
-| State not persisting | `cat ~/.codeman/state.json` | Check file permissions, disk space |
+## Performance & Limits
 
-## Performance Constraints
+Target: 20 sessions, 50 agent windows at 60fps. Limits live in `src/config/` (terminal 32MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100), most env-overridable.
 
-The app must stay fast with 20 sessions and 50 agent windows:
-- 60fps terminal (16ms batching + `requestAnimationFrame`)
-- Auto-trimming buffers (2MB terminal max)
-- Debounced state persistence (500ms)
-- SSE adaptive batching: 16ms (normal), 32ms (moderate), 50ms (rapid); immediate flush at 32KB
-- SSE backpressure handling: skip writes to backpressured clients, recover via `session:needsRefresh` on drain
-- Cached endpoints: `/api/sessions` and `/api/status` use 1s TTL caches to avoid expensive serialization
-- Frontend buffer loads: 128KB chunks via `requestAnimationFrame` to prevent UI jank
+Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired live. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
 
-## Terminal Anti-Flicker System
+**Memory leaks (24+ hour sessions)**: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 
-Claude Code uses Ink (React for terminals), which redraws the screen on every state change. Codeman implements a 6-layer anti-flicker pipeline for smooth 60fps output:
+## Scripts & Tunnel
 
-```
-PTY Output → Server Batching (16-50ms) → DEC 2026 Wrap → SSE → Client rAF → xterm.js
-```
+**`install.sh`** (repo root, 69KB) is the public entry point: `curl -fsSL <raw url> | bash` installs Node/tmux if missing, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service. It prompts for the network binding (LAN default + password prompt) and preserves the existing binding on re-runs via `read_existing_binding()`. `install.sh update` and `install.sh uninstall` also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation.
 
-**Key functions:** `server.ts:batchTerminalData()`, `server.ts:flushTerminalBatches()`, `app.js:batchTerminalWrite()`, `app.js:extractSyncSegments()`
-
-**Typical latency:** 16-32ms. Optional per-session flicker filter adds ~50ms for problematic terminals.
-
-See `docs/terminal-anti-flicker.md` for full implementation details (adaptive batching, DEC 2026 markers, edge cases).
-
-## Resource Limits
-
-Limits are centralized in `src/config/buffer-limits.ts` and `src/config/map-limits.ts`.
-
-**Buffer limits** (per session):
-| Buffer | Max | Trim To |
-|--------|-----|---------|
-| Terminal | 2MB | 1.5MB |
-| Text output | 1MB | 768KB |
-| Messages | 1000 | 800 |
-
-**Map limits** (global):
-| Resource | Max |
-|----------|-----|
-| Tracked agents | 500 |
-| Concurrent sessions | 50 |
-| SSE clients total | 100 |
-| File watchers | 500 |
-
-Use `LRUMap` for bounded caches with eviction, `StaleExpirationMap` for TTL-based cleanup.
-
-## Where to Find More Information
-
-| Topic | Location |
-|-------|----------|
-| **Respawn state machine** | `docs/respawn-state-machine.md` |
-| **Ralph Loop guide** | `docs/ralph-wiggum-guide.md` |
-| **Claude Code hooks** | `docs/claude-code-hooks-reference.md` |
-| **Terminal anti-flicker** | `docs/terminal-anti-flicker.md` |
-| **API routes** | `src/web/server.ts:buildServer()` or README.md (full endpoint tables) |
-| **SSE events** | Search `broadcast(` in `server.ts` |
-| **CLI commands** | `codeman --help` |
-| **Frontend patterns** | `src/web/public/app.js` (subagent windows, notifications) |
-| **Session statuses** | `SessionStatus` type in `src/types.ts` |
-| **Error codes** | `createErrorResponse()` in `src/types.ts` |
-| **Test utilities** | `test/respawn-test-utils.ts` |
-| **Memory leak patterns** | `test/memory-leak-prevention.test.ts` |
-| **Keyboard shortcuts** | README.md or App Settings in web UI |
-| **Mobile/SSH access** | README.md (Codeman Sessions / `sc` command) |
-| **Plan orchestrator** | `src/plan-orchestrator.ts` file header |
-| **Agent prompts** | `src/prompts/` directory |
-| **Agent Teams (experimental)** | `agent-teams/README.md`, `agent-teams/design.md` |
-| **Local echo overlay** | `docs/local-echo-overlay-plan.md` |
-| **Browser testing** | `docs/browser-testing-guide.md` |
-| **Mobile testing** | `docs/mobile-testing-report.md` |
-| **Run summary design** | `docs/run-summary-plan.md` |
-| **Performance audit** | `docs/perf-audit-first-load.md` |
-| **First-load optimization** | `docs/first-load-optimization-plan.md` |
-| **Dead code audit** | `docs/cleanup-findings.md` |
-| **Mobile test suite** | `mobile-test/README.md` |
-| **Voice input** | `docs/voice-input-plan.md` |
-| **Background keystroke forwarding** | `docs/background-keystroke-forwarding-merged-plan.md` |
-| **Respawn improvements** | `docs/respawn-improvement-plan.md` |
-| **Ralph improvements** | `docs/ralph-improvement-plan.md`, `docs/ralph-phase1-implementation.md` |
-| **Performance investigation** | `docs/performance-investigation-report.md` |
-| **Plan improvements** | `docs/plan-improvement-roadmap.md` |
-| **TypeScript improvements** | `docs/typescript-improvement-suggestions.md` |
-| **OpenCode integration** | `docs/opencode-integration.md` |
-
-## Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `scripts/tmux-manager.sh` | Safe tmux session management (use instead of direct kill commands) |
-| `scripts/tmux-chooser.sh` | Mobile-friendly tmux session picker (`sc` alias) |
-| `scripts/monitor-respawn.sh` | Monitor respawn state machine in real-time |
-| `scripts/postinstall.js` | npm postinstall hook for setup |
-| `scripts/data-generator.sh` | Generate test data for development |
-| `scripts/test-tail-links.sh` | Test clickable file links in tail output |
-| `scripts/capture-subagent-screenshots.mjs` | Capture subagent screenshots for README (uses real Claude sessions) |
-| `scripts/capture-subagent-gif.mjs` | Capture subagent GIF animations for README |
-| `scripts/mobile-screenshot.mjs` | Capture mobile UI screenshots |
-| `scripts/ralph-wizard-start.mjs` | Automate Ralph Loop startup via headless browser |
-| `scripts/ralph-wizard-prod.mjs` | Production Ralph wizard with HTTPS support |
-| `scripts/browser-comparison.mjs` | Compare Playwright, Puppeteer, and Agent-Browser frameworks |
-| `scripts/ralph-wizard-demo.mjs` | Demo Ralph Loop wizard via visible browser |
-| `scripts/test-links-browser.mjs` | Browser test for clickable terminal file links |
-| `scripts/test-patterns.mjs` | Test file path link detection regex patterns |
-| `scripts/watch-subagents.ts` | Real-time subagent transcript watcher (list, follow by session/agent ID) |
-| `scripts/capture-readme-screenshots.mjs` | Capture screenshots for README |
-| `scripts/codeman-web.service` | systemd service file for production deployment |
-
-## Memory Leak Prevention
-
-Frontend runs long (24+ hour sessions); all Maps/timers must be cleaned up.
-
-### Cleanup Patterns
-When adding new event listeners or timers:
-1. Store handler references for later removal
-2. Add cleanup to appropriate `stop()` or `cleanup*()` method
-3. For singleton watchers, store refs in class properties and remove in server `stop()`
-
-**Backend**: Clear Maps in `stop()`, null promise callbacks on error, remove watcher listeners on shutdown. Use `CleanupManager` for centralized disposal — supports timers, intervals, watchers, listeners, streams. Guard async callbacks with `if (this.cleanup.isStopped) return`.
-
-**Frontend**: Store drag/resize handlers on elements, clean up in `close*()` functions. SSE reconnect calls `handleInit()` which resets state. SSE listeners are tracked in an array and removed on reconnect to prevent accumulation.
-
-Run `npx vitest run test/memory-leak-prevention.test.ts` to verify patterns.
-
-## Common Workflows
-
-**Investigating a bug**: Start dev server (`npx tsx src/index.ts web`), reproduce in browser, check terminal output and `~/.codeman/state.json` for clues.
-
-**Adding a new API endpoint**: Define types in `types.ts`, add route in `server.ts:buildServer()`, broadcast SSE events if needed, handle in `app.js:handleSSEEvent()`.
-
-**Modifying respawn behavior**: Study `docs/respawn-state-machine.md` first. The state machine is in `respawn-controller.ts`. Use MockSession from `test/respawn-test-utils.ts` for testing.
-
-**Modifying mobile behavior**: Mobile singletons (`MobileDetection`, `KeyboardHandler`, `SwipeHandler`, `KeyboardAccessoryBar`) all have `init()`/`cleanup()` lifecycle. KeyboardHandler uses `visualViewport` API for iOS keyboard detection (100px threshold for address bar drift). All mobile handlers are re-initialized after SSE reconnect to prevent stale closures.
-
-**Adding a file watcher**: Use `ImageWatcher` as a template pattern — chokidar with `awaitWriteFinish`, burst throttling (max 20/10s), debouncing (200ms), and auto-ignore of `node_modules/.git/dist/`.
-
-## Tunnel Setup (Remote Access)
-
-Access Codeman from mobile/remote devices via Cloudflare quick tunnel.
-
-```
-Browser → Cloudflare Edge (HTTPS) → cloudflared → localhost:3000
-```
-
-**Prerequisites**: `cloudflared` installed (`cloudflared --version`), `CODEMAN_PASSWORD` set in environment.
-
-### Quick Start
-
-```bash
-# Via CLI
-./scripts/tunnel.sh start      # Start tunnel, prints public URL
-./scripts/tunnel.sh url        # Show current URL
-./scripts/tunnel.sh stop       # Stop tunnel
-
-# Via web UI: Settings → Tunnel → Toggle On
-```
-
-### systemd Service (Persistent)
-
-```bash
-# Install and enable
-cp scripts/codeman-tunnel.service ~/.config/systemd/user/
-systemctl --user daemon-reload
-systemctl --user enable --now codeman-tunnel
-
-# Check logs
-journalctl --user -u codeman-tunnel -f
-```
-
-### Auth Flow
-
-1. First request → browser shows Basic Auth prompt (username: `admin` or `CODEMAN_USERNAME`)
-2. On success → server issues `codeman_session` HttpOnly cookie (24h TTL, auto-extends on activity)
-3. Subsequent requests → cookie authenticates silently (no more prompts)
-4. SSE works automatically — `EventSource` sends same-origin cookies
-5. 10 failed attempts per IP → 429 rate limit (15-minute decay)
-
-### Security Requirements
-
-- **Always set `CODEMAN_PASSWORD`** before exposing via tunnel — without it, anyone with the URL has full access
-- Session cookies are `Secure` when using `--https` flag; through Cloudflare tunnel without `--https`, cookies are non-Secure but traffic is still encrypted end-to-end via Cloudflare
-- `/api/hook-event` bypasses auth (localhost-only Claude Code hooks need unauthenticated access)
+Other key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick), `scripts/run-beta.sh` (isolated beta instance), `scripts/build-agent-image.mjs` (docker base image), `scripts/self-update.sh` (detached updater). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Claudeman Contributors
+Copyright (c) 2024-2026 Codeman Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,22 +2,43 @@
   <img src="docs/images/codeman-title.svg" alt="Codeman" height="60">
 </p>
 
-<h2 align="center">The missing control plane for AI coding agents</h2>
+<h2 align="center">Mission control for AI coding agents</h2>
 
 <p align="center">
-  <em>Agent Visualization &bull; Zero-Lag Input Overlay &bull; Mobile-First UI &bull; Respawn Controller &bull; Multi-Session Dashboard </em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.5"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-1435%20total-22c55e?style=flat-square" alt="Tests">
+  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <a href="https://www.npmjs.com/package/aicodeman"><img src="https://img.shields.io/npm/v/aicodeman?style=flat-square&label=npm&color=22c55e" alt="npm version"></a>
+  <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo.gif" alt="Codeman — parallel subagent visualization" width="900">
+  <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
+</p>
+
+**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, or Gemini CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
+
+- **One dashboard, four CLIs** - run [Claude Code, OpenCode, Codex, or Gemini](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
+- **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
+- **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
+- **See your agents think** - [live floating windows](#live-agent-visualization) for every subagent and teammate, with real-time transcripts
+- **Nothing gets lost** - tmux persistence across restarts and network drops, exactly-once input delivery, full-scrollback replay
+- **Self-hosted and private** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman dashboard tour: session tabs per case, one-click Run for new agents, live plan usage in the header" width="900">
 </p>
 
 ---
@@ -28,30 +49,87 @@
 curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
 ```
 
-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai) (or both). After install:
+This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
+
+- **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
+- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
+- **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
+- **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
+
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (any combination works). The installer detects whichever of the four is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
 
 ```bash
 codeman web
-# Open http://localhost:3000 — press Ctrl+Enter to start your first session
+# Open http://localhost:3000 and start your first session
 ```
 
-**Update to latest version:**
+**Sharing with a small team?** Start it in multi-user mode instead: each person gets their own login and workspace.
+
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash -s update
+codeman users add alice --admin      # create the first admin account
+codeman web --multiuser              # named logins + per-user case spaces
 ```
 
+Details in [Multi-User Mode](#multi-user-mode-opt-in) below.
+
 <details>
 <summary><strong>Run as a background service</strong></summary>
 
+The installer's final menu sets this up for you (option 2) and verifies the service actually comes up before claiming success. To configure it manually instead:
+
 **Linux (systemd):**
+
 ```bash
-mkdir -p ~/.config/systemd/user && printf '[Unit]\nDescription=Codeman Web Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=%s %s/dist/index.js web\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=default.target\n' "$(which node)" "$HOME/.codeman/app" > ~/.config/systemd/user/codeman-web.service && systemctl --user daemon-reload && systemctl --user enable --now codeman-web && loginctl enable-linger $USER
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/codeman-web.service << EOF
+[Unit]
+Description=Codeman Web Server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now codeman-web
+loginctl enable-linger $USER
 ```
 
 **macOS (launchd):**
+
 ```bash
-mkdir -p ~/Library/LaunchAgents && printf '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>com.codeman.web</string><key>ProgramArguments</key><array><string>%s</string><string>%s/dist/index.js</string><string>web</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>StandardOutPath</key><string>/tmp/codeman.log</string><key>StandardErrorPath</key><string>/tmp/codeman.log</string></dict></plist>\n' "$(which node)" "$HOME/.codeman/app" > ~/Library/LaunchAgents/com.codeman.web.plist && launchctl load ~/Library/LaunchAgents/com.codeman.web.plist
+mkdir -p ~/Library/LaunchAgents
+cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.codeman.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$(which node)</string>
+    <string>$HOME/.codeman/app/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 ```
+
 </details>
 
 <details>
@@ -61,18 +139,98 @@ mkdir -p ~/Library/LaunchAgents && printf '<?xml version="1.0" encoding="UTF-8"?
 wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
 ```
 
-Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+
 </details>
 
 ---
 
+## Using Codeman — A Human's Guide
+
+A start-to-finish walkthrough for driving Codeman from the browser. If you just installed, this is where to begin.
+
+### 1. Launch the server
+
+```bash
+codeman web                       # localhost:3000 (loopback only — safe default)
+codeman web --port 8080           # custom port (or set CODEMAN_PORT)
+codeman web --https               # self-signed TLS (only needed for remote access)
+codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
+```
+
+Open the printed URL. The page is a single dashboard; everything below happens there.
+
+### 2. Create your first session
+
+Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in its own tmux-backed terminal. You choose:
+
+| Field                        | What it does                                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers.                           |
+| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Gemini`, or `Terminal` (plain shell).                                     |
+| **Model**                    | Per-session model (App Settings → Claude Model). A soft default — `/model` still works in-session.                  |
+| **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
+
+Hit start — Codeman spawns the CLI via a real PTY and streams it to your browser over SSE.
+
+### 3. Read the dashboard
+
+- **Tabs (top)** — one per session. `Alt+1`-`9` to jump, `Ctrl+Tab` for next, drag to reorder (tab order syncs across your devices).
+- **Terminal (center)** — a real `xterm.js` terminal; full TUIs render correctly. Type directly and press **Enter** to send. `Shift+Enter` inserts a newline.
+- **Side panels** — Respawn, Ralph, Orchestrator, Cron, Subagents, Settings (toggled from the toolbar).
+
+### 4. Talk to the agent
+
+- **Type prompts** straight into the terminal — input is delivered exactly-once even across reconnects (a dropped link never loses or double-sends a prompt).
+- **Paste or drag-and-drop images** directly into the session.
+- **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, with auto-silence stop).
+- **Attachments** — register external files/docs and preview Office/PDF inline.
+
+### 5. Make it autonomous
+
+| Mode             | Use it for                                                                                                                        | Where                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Respawn**      | Long unattended runs — auto-restarts the CLI on idle/limit, with adaptive timing. Presets: `solo-work`, `overnight-autonomous`, … | Respawn tab                                                         |
+| **Ralph / Todo** | A self-driving loop that tracks a todo list and keeps working until done.                                                         | Ralph tab                                                           |
+| **Orchestrator** | Turn one goal into a phased plan and drive it to completion across agents.                                                        | Orchestrator panel                                                  |
+| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Display → Header Displays)_ |
+| **Auto-resume**  | Automatically continue after a subscription rate-limit resets.                                                                    | Respawn tab (top)                                                   |
+
+### 6. Reach it from anywhere
+
+- **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
+- **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
+- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+
+### 7. Operate & maintain
+
+- **App Settings** — model, effort, permission startup mode, theme/skin, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
+- **Self-update** — git-clone installs update in place from **Settings → Updates**.
+- **Deploy your own changes** — see [Development](#development).
+
+> ⚠️ **Safety:** if you're working _inside_ a Codeman-managed session (`echo $CODEMAN_MUX` → `1`), never run `tmux kill-session` / `pkill claude` directly — use the web UI or `./scripts/tmux-manager.sh`.
+
+---
+
 ## Mobile-Optimized Web UI
 
-The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work.
+The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.
+
+<table>
+<tr>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="Mobile — landing page with QR auth" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="Mobile — active agent session" width="260"></td>
+</tr>
+<tr>
+<td align="center"><em>Landing page with QR auth</em></td>
+<td align="center"><em>Answering prompts by touch</em></td>
+<td align="center"><em>Agent working in real-time</em></td>
+</tr>
+</table>
 
 <table>
 <tr>
-<td rowspan="8" width="320"><img src="docs/screenshots/mobile-keyboard-open.png" alt="Mobile — keyboard open" width="300"></td>
 <th>Terminal Apps</th>
 <th>Codeman Mobile</th>
 </tr>
@@ -82,11 +240,27 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
 <tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr>
 <tr><td>Manual reconnect</td><td>tmux persistence</td></tr>
 <tr><td>No agent visibility</td><td>Background agents in real-time</td></tr>
-<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code></tr>
+<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr>
+<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
 </table>
 
-- **Swipe navigation** — left/right on the terminal to switch sessions (80px threshold, 300ms)
+### Secure QR Code Authentication
+
+Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
+
+Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
+
+The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+### Touch-Optimized Interface
+
+<p align="center">
+  <img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="560">
+</p>
+
 - **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard. Destructive commands (`/clear`, `/compact`) require a double-press to confirm — first tap arms the button, second tap executes — so you never fire one by accident on a bumpy commute
+- **Dedicated Enter button** — submitting is a constant need on a touch keyboard, so the phone toolbar gives it a button of its own. It replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded. Starting a shell moves into the Run dropdown (`Terminal / Shell`), which is the rarer action
+- **Swipe navigation** — left/right on the terminal to switch sessions (80px threshold, 300ms)
 - **Smart keyboard handling** — toolbar and terminal shift up when keyboard opens (uses `visualViewport` API with 100px threshold for iOS address bar drift)
 - **Safe area support** — respects iPhone notch and home indicator via `env(safe-area-inset-*)`
 - **44px touch targets** — all buttons meet iOS Human Interface Guidelines minimum sizes
@@ -107,7 +281,7 @@ codeman web --https
 Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.
 
 <p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="Subagent Visualization" width="900">
+  <img src="docs/images/subagent-windows-20260724.png" alt="Subagent Visualization: three parallel Explore agents as floating windows with live tool-call feeds" width="900">
 </p>
 
 - **Floating terminal windows** — draggable, resizable panels for each agent with a live activity log showing every tool call, file read, and progress update as it happens
@@ -116,10 +290,22 @@ Watch background agents work in real-time. Codeman monitors agent activity and d
 - **Auto-behavior** — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
 - **Nested agents** — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)
 
+Multi-agent Workflow runs ("ultracode") get the same treatment: a floating run window tracks the whole workflow live, with phases, per-agent token counts, and the current tool of every agent:
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode workflow visualization: a live run window with per-agent tokens and phases" width="900">
+</p>
+
+**Agent Teams** — first-class support for Claude Code's native multi-agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). `TeamWatcher` polls `~/.claude/teams/`, matches teammates to their lead session, and surfaces them as live subagent windows with **team-aware idle detection** — so the Respawn Controller won't fire while teammates are still working. See [`docs/agent-teams/`](docs/agent-teams/).
+
 ---
 
 ## Zero-Lag Input Overlay
 
+<p align="center">
+  <img src="docs/images/zerolag-demo.gif" alt="Zerolag Demo — local echo vs server echo side-by-side" width="900">
+</p>
+
 When accessing your coding agent remotely (VPN, Tailscale, SSH tunnel), every keystroke normally takes 200-300ms to round-trip. Codeman implements a **Mosh-inspired local echo system** that makes typing feel instant regardless of latency.
 
 A pixel-perfect DOM overlay inside xterm.js renders keystrokes at 0ms. Background forwarding silently sends every character to the PTY in 50ms debounced batches, so Tab completion, `Ctrl+R` history search, and all shell features work normally. When the server echo arrives 200-300ms later, the overlay seamlessly disappears and the real terminal text takes over — the transition is invisible.
@@ -143,12 +329,27 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 ```
 
 - **Multi-layer idle detection** — completion messages, AI-powered idle check, output silence, token stability
+- **Auto-resume on usage limit** _(opt-in, off by default)_ — when Claude halts on a subscription limit ("You've hit your limit · resets 3pm"), Codeman parses the reset time, waits it out plus a 2-minute safety buffer, then dismisses the rate-limit dialog and sends `continue` — so an overnight run survives the 5-hour window instead of stalling until morning. Recognizes every Claude Code limit-message format, retries if still limited, survives Codeman restarts, and holds respawn cycles while paused so `/clear` can't wipe the waiting conversation. Enable per session at the top of the Respawn tab
 - **Circuit breaker** — prevents respawn thrashing when Claude is stuck (CLOSED -> HALF_OPEN -> OPEN states, tracks consecutive no-progress and repeated errors)
 - **Health scoring** — 0-100 health score with component scores for cycle success, circuit breaker state, iteration progress, and stuck recovery
 - **Built-in presets** — `solo-work` (3s idle, 60min), `subagent-workflow` (45s, 240min), `team-lead` (90s, 480min), `ralph-todo` (8s, 480min), `overnight-autonomous` (10s, 480min)
 
 ---
 
+## Orchestrator Loop
+
+Beyond single-session respawn, the **Orchestrator** turns a high-level goal into a phased plan and drives it to completion across multiple agents — a state machine that runs `idle → planning → approval → executing → verifying → (replanning) → completed`.
+
+- **Plan, then execute** — generates a phased plan from your goal and pauses for approval before touching anything; reject with feedback to regenerate
+- **Per-phase verification gates** — each phase is verified before the next begins; on failure the orchestrator replans instead of barreling ahead
+- **Multi-agent execution** — fans phases out to team agents / a task queue, coordinating work too big for one session
+- **Crash-safe** — full state persists under the `orchestrator` key in `state.json`, so it survives restarts
+- **Driven from the UI or API** — the Orchestrator panel, or `POST /api/orchestrator/start` → `/approve` → `/status` (10 endpoints)
+
+> Distinct from Ralph (a single-session autonomous loop): the orchestrator coordinates multi-phase, multi-agent execution. Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
+
+---
+
 ## Multi-Session Dashboard
 
 Run **20 parallel sessions** with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.
@@ -161,12 +362,31 @@ Run **20 parallel sessions** with full visibility — real-time xterm.js termina
 
 Every session runs inside **tmux** — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Managed sessions are environment-tagged so the agent won't kill its own session.
 
+### Session Manager & Command Palette
+
+`Ctrl/Cmd/Alt+K` opens a fuzzy session palette; **Browse all sessions** opens the Session Manager: one deduped list of everything Codeman knows about (live sessions, past sessions from state and lifecycle history, and Claude transcripts), each row showing its first and most recent prompt.
+
+- **Pinning**: pin a session to float it to the top of the list. Pinned sessions even survive kill (they demote to a lightweight stopped entry that stays visible and resumable).
+- **Name retention**: resuming a past session keeps its original name instead of minting a new one.
+- **Cross-device tab order**: drag-reordered tabs persist server-side, so your ordering follows you from desktop to phone.
+
+### Hostname-Aware Window Title
+
+Running Codeman on multiple hosts (laptop, dev box, NAS)? The browser tab title is `codeman:<hostname>` so you can tell which backend each tab points at without clicking in:
+
+```bash
+codeman web                                # codeman:<os.hostname()>
+codeman web --title-hostname dev-box       # codeman:dev-box (manual override for noisy hostnames)
+```
+
+The title is templated into the served HTML on first byte, so it's correct from the very first paint and works without JavaScript. The same hostname prefix is applied to the tab-flash format (`⚠️ (N) codeman:<host>`) and to OS-level desktop notifications (`codeman:<host>: <event>`), so cross-host alerts in the system notification center are also unambiguous.
+
 ### Smart Token Management
 
-| Threshold | Action | Result |
-|-----------|--------|--------|
+| Threshold       | Action          | Result                             |
+| --------------- | --------------- | ---------------------------------- |
 | **110k tokens** | Auto `/compact` | Context summarized, work continues |
-| **140k tokens** | Auto `/clear` | Fresh start with `/init` |
+| **140k tokens** | Auto `/clear`   | Fresh start with `/init`           |
 
 ### Notifications
 
@@ -194,6 +414,230 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 
 ---
 
+## More Features
+
+- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
+- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
+- **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
+- **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
+- **Voice input** — dictate prompts with Deepgram Nova-3 (Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
+- **Image input** — paste or drag-and-drop images straight into a session
+- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
+- **Multi-monitor span** _(macOS)_ — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
+- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Display → Header Displays
+- **CJK / IME input** — full composition support for Chinese / Japanese / Korean
+- **OS notifications & hostname-aware titles** — desktop alerts and tab titles are prefixed `codeman:<host>` so multi-host setups stay unambiguous
+
+---
+
+## Isolated Docker Sessions
+
+Run a case inside its own hardened Docker container instead of directly on your host — for security isolation, reproducible toolchains, and one-click portability.
+
+- **One click** — on **New Case → Create New**, tick **🐳 Run in an isolated Docker container**. Codeman creates the case folder, spins up a container with default settings, and starts the agent inside it. No host/image/network fields to fill in.
+- **Resource templates** — expand the checkbox for a **Small / Medium / Large / GPU** preset (memory, CPUs, GPU), or set your own. **Disk is elastic** — storage grows as data flows in, no fixed cap.
+- **Shared per-case container** — many sessions can `docker exec` into the same container; killing one session never tears the container out from under the others.
+- **Hardened by default** — non-root, `--cap-drop ALL`, `no-new-privileges`, PID/memory caps, never `--privileged` or the docker socket; a **sealed** profile (no host credentials, network off) is one toggle away.
+- **Seamless auth, isolated credentials** — your host Claude / Codex / Gemini / OpenCode logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
+- **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
+- **Durable** — reconnect after a restart lands back in the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript.
+
+Prerequisite: just Docker (or Podman). The agent base image builds itself automatically on first use, with progress streamed to the UI (or pre-build it with `node scripts/build-agent-image.mjs`). Full guide: [`docs/docker-cases.md`](docs/docker-cases.md).
+
+---
+
+## Remote SSH Sessions
+
+Point a case at another machine and run the agent **there**, over SSH, with the same dashboard, mobile UI, and autonomy features. Your laptop is just a window onto a session that lives on the remote host.
+
+- **Durable by design**: the agent runs inside a dedicated tmux session on the remote host, so a dropped SSH connection, network change, or laptop sleep never kills the run. Reconnecting lands back in the same live conversation.
+- **Auto-reconnect**: a bounded-backoff watcher notices a dead SSH pane and silently reattaches to the still-running remote session (kill-switch in settings; intentional kills are never revived).
+- **Discover & attach**: list the `codeman-*` sessions already running on a host (started by that machine's own Codeman, or by another operator) and attach to one. Attached sessions you don't own **detach on tab close, never kill**.
+- **Shared sessions**: several clients can attach the same remote session at different window sizes without clamping each other; discovery shows a "shared" badge with the client count.
+- **Injection-safe**: every ssh command line flows through a single shell-escaping builder, and host/path/identity fields are schema-guarded.
+
+Set it up under **New Case → Remote** (host, user, identity file, optional jump host). Full design: [`docs/remote-sessions.md`](docs/remote-sessions.md).
+
+---
+
+## Multi-User Mode (opt-in)
+
+Share one Codeman with a small trusted team, each person getting their own login and workspace. **Off by default** — without the flag, nothing changes.
+
+Enable with `codeman web --multiuser` (or `CODEMAN_MULTIUSER=1`). Create the first admin, then manage users from the CLI or the **Users** tab in App Settings:
+
+```bash
+codeman users add alice --admin      # prompts for a password (or --password-stdin)
+codeman users add bob                # a regular user
+codeman users list
+```
+
+- **Per-user spaces** — each user's cases live under `~/codeman-users/<name>/cases`; sessions, cases, search, and real-time events are scoped to their owner. Admins see everything.
+- **Individually revocable logins** — named users with scrypt-hashed passwords in `~/.codeman/users.json`; disable, reset (one-time password), or delete an account at any time. Admin actions are audited to `~/.codeman/admin-audit.jsonl`.
+- **Safer defaults for regular users** — non-admins run Claude in `--permission-mode auto` (Anthropic's classifier-guarded mode); raw shell sessions, cron `launchCommand`, and skip-permissions require an explicit per-user grant.
+
+> ⚠️ **This separates workspaces; it does not sandbox users from each other.** Every session runs as the same OS account, so a determined user's agent can still reach another user's files. For real isolation, pair users with **Docker cases** or run separate instances under separate OS accounts. See [`docs/multi-user-plan.md`](docs/multi-user-plan.md) and the multi-user section of [`docs/security-architecture.md`](docs/security-architecture.md).
+
+---
+
+## Remote Access — Cloudflare Tunnel
+
+Access Codeman from your phone or any device outside your local network using a free [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) — no port forwarding, no DNS, no static IP required.
+
+```
+Browser (phone/tablet) → Cloudflare Edge (HTTPS) → cloudflared → localhost:3000
+```
+
+**Prerequisites:** Install [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) and set `CODEMAN_PASSWORD` in your environment.
+
+```bash
+# Quick start
+./scripts/tunnel.sh start      # Start tunnel, prints public URL
+./scripts/tunnel.sh url        # Show current URL
+./scripts/tunnel.sh stop       # Stop tunnel
+./scripts/tunnel.sh status     # Service status + URL
+```
+
+The script auto-installs a systemd user service on first run. The tunnel URL is a randomly generated `*.trycloudflare.com` address that changes each time the tunnel restarts.
+
+<details>
+<summary><strong>Persistent tunnel (survives reboots)</strong></summary>
+
+```bash
+# Enable as a persistent service
+systemctl --user enable codeman-tunnel
+loginctl enable-linger $USER
+
+# Or via the Codeman web UI: Settings → Tunnel → Toggle On
+```
+
+</details>
+
+<details>
+<summary><strong>Authentication</strong></summary>
+
+1. First request → browser shows Basic Auth prompt (username: `admin` or `CODEMAN_USERNAME`)
+2. On success → server issues a `codeman_session` cookie (24h TTL, auto-extends on activity)
+3. Subsequent requests authenticate silently via cookie
+4. 10 failed attempts per IP → 429 rate limit (15-minute decay)
+
+**Always set `CODEMAN_PASSWORD`** before exposing via tunnel — without it, anyone with the URL has full access to your sessions.
+
+</details>
+
+### QR Code Authentication
+
+Typing a password on a phone keyboard is terrible. Codeman solves this with **ephemeral single-use QR tokens** — scan the code on your desktop, and your phone is instantly authenticated. No password prompt, no typing, no clipboard.
+
+```
+Desktop displays QR  →  Phone scans  →  GET /q/Xk9mQ3  →  Server validates
+→  Token atomically consumed (single-use)  →  Session cookie issued  →  302 to /
+→  Desktop notified: "Device authenticated via QR"  →  New QR auto-generated
+```
+
+Someone who only has the bare tunnel URL (without the QR) still hits the standard password prompt. The QR is the fast path; the password is the fallback.
+
+#### How It Works
+
+The server maintains a rotating pool of short-lived, single-use tokens. Each token consists of a 256-bit secret (`crypto.randomBytes(32)`) paired with a 6-character base62 short code used as an opaque lookup key in the URL path. The QR code encodes a URL like `https://abc-xyz.trycloudflare.com/q/Xk9mQ3` — the short code is a pointer, not the secret itself, so it never leaks through browser history, `Referer` headers, or Cloudflare edge logs.
+
+Every **60 seconds**, the server automatically rotates to a fresh token. The previous token remains valid for a **90-second grace period** to handle the race where you scan right as rotation happens — after that, it's dead. Each token is **single-use**: the moment a phone successfully scans it, the token is atomically consumed and a new one is immediately generated for the desktop display.
+
+#### Security Design
+
+The design is informed by ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025), which found 47 of the top-100 websites vulnerable to QR auth attacks due to 6 critical design flaws across 42 CVEs. Codeman addresses all six:
+
+| USENIX Flaw                                | Mitigation                                                                                                       |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Flaw-1**: Missing single-use enforcement | Token atomically consumed on first scan — replays always fail                                                    |
+| **Flaw-2**: Long-lived tokens              | 60s TTL with 90s grace, auto-rotation via timer                                                                  |
+| **Flaw-3**: Predictable token generation   | `crypto.randomBytes(32)` — 256-bit entropy. Short codes use rejection sampling to eliminate modulo bias          |
+| **Flaw-4**: Client-side token generation   | Server-side only — tokens never leave the server until embedded in the QR                                        |
+| **Flaw-5**: Missing status notification    | Desktop toast: _"Device [IP] authenticated via QR (Safari). Not you? [Revoke]"_ — real-time QRLjacking detection |
+| **Flaw-6**: Inadequate session binding     | IP + User-Agent stored for audit. Manual session revocation via API. HttpOnly + Secure + SameSite=lax cookies    |
+
+#### Timing-Safe Lookup
+
+Short codes are stored in a `Map<shortCode, TokenRecord>`. Validation uses `Map.get()` — a hash-based O(1) lookup that reveals nothing about the target string through response timing. There is no character-by-character string comparison anywhere in the hot path, eliminating timing side-channel attacks entirely.
+
+#### Rate Limiting (Dual Layer)
+
+QR auth has its own rate limiting, completely independent from password auth:
+
+- **Per-IP**: 10 failed QR attempts per IP trigger a 429 block (15-minute decay window) — separate counter from Basic Auth failures, so a fat-fingered password doesn't burn your QR budget
+- **Global**: 30 QR attempts per minute across all IPs combined — defends against distributed brute force. With 62^6 = 56.8 billion possible short codes and only ~2 valid at any time, brute force is computationally infeasible regardless
+
+#### QR Code Size Optimization
+
+The URL is kept deliberately short (`/q/` path + 6-char code = ~53-56 total characters) to target **QR Version 4** (33x33 modules) instead of Version 5 (37x37). Smaller QR codes scan faster on budget phones — modern devices read Version 4 in 100-300ms. The `/q/` prefix saves 7 bytes compared to `/qr-auth/`, which alone is the difference between QR versions.
+
+#### Desktop Experience
+
+The QR display auto-refreshes every 60 seconds via SSE with the SVG embedded directly in the event payload (~2-5KB) — no extra HTTP fetch, sub-50ms refresh. A countdown timer shows time remaining. A "Regenerate" button instantly invalidates all existing tokens and creates a fresh one (useful if you suspect the QR was photographed).
+
+When someone authenticates via QR, the desktop shows a notification toast with the device's IP and browser — if it wasn't you, one click revokes all sessions.
+
+#### Threat Coverage
+
+| Threat                   | Why it doesn't work                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **QR screenshot shared** | Single-use: consumed on first scan. 60s TTL: expired before the attacker can act. Desktop notification alerts you immediately.             |
+| **Replay attack**        | Atomic single-use consumption + 60s TTL. Old URLs always return 401.                                                                       |
+| **Cloudflare edge logs** | Short code is an opaque 6-char lookup key, not the real 256-bit token. Single-use means replaying from logs always fails.                  |
+| **Brute force**          | 56.8 billion combinations, ~2 valid at any time, dual-layer rate limiting blocks well before statistical feasibility.                      |
+| **QRLjacking**           | 60s rotation forces real-time relay. Desktop toast provides instant detection. Self-hosted single-user context makes phishing implausible. |
+| **Timing attack**        | Hash-based Map lookup — no string comparison timing leak.                                                                                  |
+| **Session cookie theft** | HttpOnly + Secure + SameSite=lax + 24h TTL. Manual revocation at `POST /api/auth/revoke`.                                                  |
+
+#### How It Compares
+
+| Platform         | Model                                                                                                         | Comparison                                                                                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Discord**      | Long-lived token, no confirmation, [repeatedly exploited](https://owasp.org/www-community/attacks/Qrljacking) | Codeman: single-use + TTL + notification                                                                                                                                                       |
+| **WhatsApp Web** | Phone confirms "Link device?", ~60s rotation                                                                  | Comparable rotation; WhatsApp adds explicit confirmation (acceptable tradeoff for single-user)                                                                                                 |
+| **Signal**       | Ephemeral public key, E2E encrypted channel                                                                   | Stronger crypto, but [exploited by Russian state actors in 2025](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger) via social engineering despite it |
+
+> Full design rationale, security analysis, and implementation details: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+---
+
+## Security
+
+By default Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control _who_ that is. (The startup permission mode is configurable; see below.) Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **Found a vulnerability?** See [`SECURITY.md`](.github/SECURITY.md) for private disclosure and the list of known limitations.
+
+### Network & access
+
+- **Loopback by default** — the server binary binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box (the guided installer asks about network access and configures the binding + password for you). Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
+- **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
+- **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers _immediately_ even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
+- **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Claude CLI → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
+
+### Always-on browser hardening (v0.9.5)
+
+These run for **every** request — before auth, even on the default no-password loopback install:
+
+- **Host-header allowlist → blocks DNS rebinding.** A custom domain rebound to `127.0.0.1` is rejected with `403 host not allowed` before any handler runs. Allowed: `localhost`, any IP literal, the bind host, `.ts.net` / `.trycloudflare.com` / `.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS` (add custom reverse-proxy domains here — comma-separated; exact host or leading-dot `.suffix` for subdomains)
+- **Cross-site Origin / CSRF guard.** On state-changing methods (`POST`/`PUT`/`PATCH`/`DELETE`) the `Origin` must pass the same allowlist, else `403 cross-site request blocked`. A _missing_ Origin is allowed (so `curl`, the CLI, and Claude Code hooks keep working); only a present-but-foreign or opaque `null` origin is rejected
+- **Raw `text/plain` bodies.** The global parser no longer JSON-parses `text/plain`, closing the CORS "simple request" CSRF vector where a cross-site `fetch` could smuggle JSON into a write route with no preflight
+- **WebSocket origin validation.** The terminal WS upgrade runs the same Host + Origin check and closes with code `4003` on failure (anti-CSWSH)
+- **XSS-escaped agent output.** AI-derived strings (tool names, command arguments, subagent descriptions) are HTML-escaped at every injection site before rendering in the subagent / activity panels
+
+### Input, files & headers
+
+- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env-prefix allowlist gates which settings each CLI can receive
+- **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 50 MB raw & download; `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
+- **Security headers** — `Content-Security-Policy` (`default-src 'self'`, every exception enumerated), `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, HSTS over HTTPS, and CORS reflected **only** for `localhost` / `127.0.0.1` / `::1`
+
+### Supply chain & isolation
+
+- **Pinned & verified deps** — security-sensitive transitive deps are forced to patched versions via npm `overrides`; lockfile integrity is checked on every commit/PR (all entries resolve to `registry.npmjs.org` with `sha512` hashes). Public assets are NUL-byte-scanned and `node --check`-validated in CI
+- **Multi-instance isolation** — `CODEMAN_INSTANCE` scopes both the tmux socket (`-L codeman-<name>`) and data dir (`~/.codeman-<name>`) so two instances never attach each other's live sessions
+
+> Mobile login uses single-use, 60-second QR tokens — see [QR Code Authentication](#qr-code-authentication) above for the full design (it addresses all 6 flaws from USENIX Security 2025's QR-login study).
+
+---
+
 ## SSH Alternative (`sc`)
 
 If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
@@ -210,57 +654,182 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 
 ## Keyboard Shortcuts
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl+Enter` | Quick-start session |
-| `Ctrl+W` | Close session |
-| `Ctrl+Tab` | Next session |
-| `Ctrl+K` | Kill all sessions |
-| `Ctrl+L` | Clear terminal |
-| `Ctrl+Shift+R` | Restore terminal size |
-| `Ctrl/Cmd +/-` | Font size |
-| `Escape` | Close panels |
+> Ctrl bindings also accept Cmd on macOS.
+
+| Shortcut                        | Action                                                        |
+| ------------------------------- | ------------------------------------------------------------- |
+| `Ctrl/Cmd+W`                    | Kill active session                                           |
+| `Ctrl/Cmd/Option+K`             | Find open session or start a new one                          |
+| `Ctrl/Cmd+Tab`                  | Next session                                                  |
+| `Alt/Option+[` / `Alt/Option+]` | Previous / next session                                       |
+| `Alt/Option+1`-`Alt/Option+9`   | Switch to tab N (physical keys, so macOS Option layouts work) |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right                                  |
+| `Ctrl/Cmd+L`                    | Clear terminal                                                |
+| `Ctrl+Shift+R`                  | Restore terminal size                                         |
+| `Ctrl+Shift+V`                  | Toggle voice input                                            |
+| `Ctrl/Cmd +` / `-`              | Font size                                                     |
+| `Ctrl/Cmd+?`                    | Keyboard help                                                 |
+| `Shift+Enter`                   | Insert newline (sent to terminal)                             |
+| `Escape`                        | Close panels & modals                                         |
+
+---
+
+## Driving Codeman from an Agent — Programmatic Guide
+
+For AI agents and automation that control Codeman without a browser: an agent that spins up worker sessions, a CI bot, or **Claude Code running _inside_ a Codeman session orchestrating other sessions**. Everything the UI does is HTTP + a CLI, so an agent can do it too.
+
+### Detect that you're inside Codeman
+
+When a CLI runs in a Codeman-managed session, these environment variables are set — read them instead of hardcoding anything:
+
+| Variable                   | Meaning                                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `CODEMAN_MUX=1`            | You're in a managed tmux session. **Never** `tmux kill-session` / `pkill claude` / `pkill tmux` — you'll kill yourself or a sibling. |
+| `CODEMAN_API_URL`          | Base URL of the API (e.g. `https://127.0.0.1:3000`). Use it for every call below.                                                    |
+| `CODEMAN_SESSION_ID`       | _Your own_ session id. Use it to avoid acting on yourself.                                                                           |
+| `CODEMAN_HOOK_SECRET_FILE` | Path to the hook secret (required on `/api/hook-event` while a managed tunnel is up).                                                |
+
+### Rules of the road (read before you POST)
+
+1. **Single-line input only.** Programmatic input is sent as literal text **+ Enter** in one shot. Multi-line strings break the agent TUI (Ink) — send one line, or split into multiple calls.
+2. **Make input idempotent.** Include a stable `clientId` and a monotonic per-session `seq` on `POST …/input`. The server de-duplicates, so a retry after a dropped connection can't double-deliver a prompt.
+3. **Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic auth (user `admin` or `CODEMAN_USERNAME`) or a `codeman_session` cookie. The default loopback install is passwordless. A missing `Origin` header is allowed, so plain `curl` works; cross-site browser origins are rejected (CSRF guard).
+4. **Response envelope.** Most endpoints return `{ "success": true, "data": … }` (errors: `{ "success": false, "error", "errorCode" }`). A few legacy GETs return bare bodies — **handle both** (`body.data ?? body`).
+5. **`/api/v1/*`** is a stable alias of `/api/*`.
+
+### Recipes
+
+```bash
+API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
+# (add  -u admin:"$CODEMAN_PASSWORD"  to each call if a password is set)
+
+# 1. See what's running
+curl -s "$API/api/sessions" | jq '.data // .'
+
+# 2. Spin up a worker session (a "case" = named working dir)
+curl -s -X POST "$API/api/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
+
+# 3. Send a prompt into a session (exactly-once: clientId + seq)
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+
+# 4. Read the terminal back
+curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+
+# 5. Stream live events (session output, agent activity, status)
+curl -sN "$API/api/events"          # Server-Sent Events
+
+# 6. Schedule recurring work (cron-style job)
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
+       "promptMode":"inline_text","promptText":"Update dependencies and open a PR",
+       "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
+       "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
+
+# 7. Inspect background sub-agents and their transcripts
+curl -s "$API/api/subagents" | jq '.data // .'
+curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
+
+# 8. Whole-system snapshot (sessions, settings, respawn, stats)
+curl -s "$API/api/status" | jq
+```
+
+### Or use the bundled CLI
+
+The same operations are available as commands (`codeman <cmd>`, aliases in parentheses) — handy from a shell tool inside a session:
+
+```bash
+codeman session start -d /path/to/repo   # (s)  start a session
+codeman session list                     #      list sessions
+codeman session logs <id>                #      tail output
+codeman task add "fix the failing test"  # (t)  queue a task
+codeman ralph start --min-hours 8        # (r)  launch the autonomous loop
+codeman attach <path>                     #      attach a Claude hook context
+```
+
+### Hooks (events flowing _back_ to Codeman)
+
+Codeman registers Claude Code hooks that `POST /api/hook-event` (`permission_prompt`, `idle_prompt`, `stop`, `task_completed`, …) so the dashboard reacts in real time. This endpoint is auth-exempt on loopback but, under a managed tunnel, requires the `X-Codeman-Hook-Secret` header (read it from `$CODEMAN_HOOK_SECRET_FILE`). You normally don't call this by hand — Codeman wires it up — but it's how the autonomy layers "see" what the agent is doing.
+
+> Full endpoint list and request/response shapes follow.
 
 ---
 
 ## API
 
+REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE stream and a WebSocket terminal channel. All responses use the `ApiResponse<T>` envelope (`{success, data}` / `{success, error, errorCode}`); `/api/v1/*` is a stable alias. A representative subset:
+
 ### Sessions
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/sessions` | List all |
-| `POST` | `/api/quick-start` | Create case + start session |
-| `DELETE` | `/api/sessions/:id` | Delete session |
-| `POST` | `/api/sessions/:id/input` | Send input |
+
+| Method   | Endpoint                   | Description                                                                        |
+| -------- | -------------------------- | ---------------------------------------------------------------------------------- |
+| `GET`    | `/api/sessions`            | List all                                                                           |
+| `POST`   | `/api/quick-start`         | Create case + start session (`{caseName?, mode?, effort?, envOverrides?}`)         |
+| `POST`   | `/api/sessions/:id/input`  | Send input (`{input, useMux?, clientId?, seq?}` — `clientId`+`seq` = exactly-once) |
+| `GET`    | `/api/sessions/:id/output` | Read terminal output                                                               |
+| `GET`    | `/api/sessions/unified`    | Unified live + history list (Session Manager) — `?q=&limit=`                       |
+| `POST`   | `/api/sessions/:id/pin`    | Pin/unpin in the Session Manager (`{pinned}`)                                      |
+| `PUT`    | `/api/session-order`       | Sync tab order across devices (`{order: [ids]}`)                                   |
+| `DELETE` | `/api/sessions/:id`        | Delete session                                                                     |
 
 ### Respawn
-| Method | Endpoint | Description |
-|--------|----------|-------------|
+
+| Method | Endpoint                           | Description                |
+| ------ | ---------------------------------- | -------------------------- |
 | `POST` | `/api/sessions/:id/respawn/enable` | Enable with config + timer |
-| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
-| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
+| `POST` | `/api/sessions/:id/respawn/stop`   | Stop controller            |
+| `PUT`  | `/api/sessions/:id/respawn/config` | Update config              |
 
 ### Ralph / Todo
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/sessions/:id/ralph-state` | Get loop state + todos |
-| `POST` | `/api/sessions/:id/ralph-config` | Configure tracking |
+
+| Method | Endpoint                         | Description            |
+| ------ | -------------------------------- | ---------------------- |
+| `GET`  | `/api/sessions/:id/ralph-state`  | Get loop state + todos |
+| `POST` | `/api/sessions/:id/ralph-config` | Configure tracking     |
+
+### Orchestrator
+
+| Method | Endpoint                    | Description                     |
+| ------ | --------------------------- | ------------------------------- |
+| `POST` | `/api/orchestrator/start`   | Start orchestration from a goal |
+| `POST` | `/api/orchestrator/approve` | Approve the generated plan      |
+| `GET`  | `/api/orchestrator/status`  | Current phase + progress        |
+| `POST` | `/api/orchestrator/stop`    | Stop and clean up               |
+
+### Cron (scheduled jobs)
+
+| Method           | Endpoint                     | Description             |
+| ---------------- | ---------------------------- | ----------------------- |
+| `GET` / `POST`   | `/api/cron/jobs`             | List / create cron jobs |
+| `PUT` / `DELETE` | `/api/cron/jobs/:id`         | Update / delete a job   |
+| `PUT`            | `/api/cron/jobs/:id/enabled` | Enable / disable        |
+| `POST`           | `/api/cron/jobs/:id/run`     | Run now                 |
+| `GET`            | `/api/cron/jobs/:id/runs`    | Run history             |
 
 ### Subagents
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/subagents` | List all background agents |
-| `GET` | `/api/subagents/:id` | Agent info and status |
-| `GET` | `/api/subagents/:id/transcript` | Full activity transcript |
-| `DELETE` | `/api/subagents/:id` | Kill agent process |
+
+| Method   | Endpoint                        | Description                |
+| -------- | ------------------------------- | -------------------------- |
+| `GET`    | `/api/subagents`                | List all background agents |
+| `GET`    | `/api/subagents/:id`            | Agent info and status      |
+| `GET`    | `/api/subagents/:id/transcript` | Full activity transcript   |
+| `DELETE` | `/api/subagents/:id`            | Kill agent process         |
 
 ### System
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/events` | SSE stream |
-| `GET` | `/api/status` | Full app state |
-| `POST` | `/api/hook-event` | Hook callbacks |
-| `GET` | `/api/sessions/:id/run-summary` | Timeline + stats |
+
+| Method | Endpoint                        | Description                                    |
+| ------ | ------------------------------- | ---------------------------------------------- |
+| `GET`  | `/api/events`                   | SSE stream                                     |
+| `GET`  | `/api/status`                   | Full app state                                 |
+| `POST` | `/api/hook-event`               | Hook callbacks                                 |
+| `GET`  | `/api/system/update/check`      | Check for a new release                        |
+| `POST` | `/api/system/update`            | Self-update (git-clone installs)               |
+| `POST` | `/api/clipboard`                | Push text to all connected browsers (`{text}`) |
+| `GET`  | `/api/sessions/:id/run-summary` | Timeline + stats                               |
 
 ---
 
@@ -280,11 +849,13 @@ flowchart TB
             S1["Session (PTY)"]
             S2["Session (PTY)"]
             RC["Respawn Controller"]
+            ORC["Orchestrator Loop"]
         end
 
         subgraph Detection["Detection Layer"]
             RT["Ralph Tracker"]
             SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
+            TW["Team Watcher<br/><small>~/.claude/teams/*</small>"]
         end
 
         subgraph Persistence["Persistence Layer"]
@@ -293,7 +864,7 @@ flowchart TB
         end
 
         subgraph External["External"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
             BG["Background Agents<br/><small>(Task tool)</small>"]
         end
     end
@@ -304,14 +875,17 @@ flowchart TB
     SM --> S1
     SM --> S2
     SM --> RC
+    SM --> ORC
     SM --> SS
     S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
+    ORC --> SCR
     SCR --> CLI
     SW --> BG
     SW --> SSE
+    TW --> SSE
 ```
 
 ---
@@ -322,13 +896,30 @@ flowchart TB
 npm install
 npx tsx src/index.ts web    # Dev mode
 npm run build               # Production build
-npm test                    # Run tests
+npm run test:ci             # Run tests (the CI suite; browser suites need extra setup)
 ```
 
 See [CLAUDE.md](./CLAUDE.md) for full documentation.
 
 ---
 
+## Codebase Quality
+
+The codebase went through a comprehensive 7-phase refactoring that eliminated god objects, centralized configuration, and established modular architecture:
+
+| Phase                    | What changed                                                                                                 | Impact                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| **Performance**          | Cached endpoints, SSE adaptive batching, buffer chunking                                                     | Sub-16ms terminal latency                  |
+| **Route extraction**     | `server.ts` split into 15 domain route modules + auth middleware + port interfaces                           | **−67%** server.ts LOC (6,736 → 2,254)     |
+| **Domain splitting**     | `types.ts` → 16 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files                          |
+| **Frontend modules**     | `app.js` → 18 extracted modules across infra, domain & feature layers                                        | app.js core down to **~3.4K LOC**          |
+| **Config consolidation** | ~70 scattered magic numbers → 10 domain-focused config files                                                 | Zero cross-file duplicates                 |
+| **Test infrastructure**  | Shared mock library, 12 route test files, consolidated MockSession                                           | Testable route handlers via `app.inject()` |
+
+Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
+
+---
+
 ## Published Packages
 
 ### [`xterm-zerolag-input`](https://www.npmjs.com/package/xterm-zerolag-input)
@@ -345,6 +936,14 @@ npm install xterm-zerolag-input
 
 ---
 
+## Versioning
+
+Codeman follows [SemVer](https://semver.org/). What the version number actually
+commits to — and what counts as internal (the HTTP/SSE API, on-disk state,
+experimental features) — is spelled out in
+[`docs/versioning-policy.md`](docs/versioning-policy.md). If you script against
+the HTTP API, pin to an exact version.
+
 ## License
 
 MIT — see [LICENSE](LICENSE)
@@ -354,3 +953,8 @@ MIT — see [LICENSE](LICENSE)
 <p align="center">
   <strong>Track sessions. Visualize agents. Control respawn. Let it run while you sleep.</strong>
 </p>
+
+<p align="center">
+  If Codeman saves you time, <a href="https://github.com/Ark0N/Codeman/stargazers">a star</a> helps other people find it.<br>
+  Bug reports and feature ideas are welcome in <a href="https://github.com/Ark0N/Codeman/issues">Issues</a>.
+</p>

README.zh-CN.md

@@ -0,0 +1,941 @@
+<p align="center">
+  <img src="docs/images/codeman-title.svg" alt="Codeman" height="60">
+</p>
+
+<h2 align="center">AI 编程智能体的任务控制中心</h2>
+
+<p align="center">
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> &bull; <strong>简体中文</strong>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
+  <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
+  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
+</p>
+
+<p align="center">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — 并行子智能体可视化" width="900">
+</p>
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman 仪表盘导览：按项目分组的会话标签页、一键 Run 启动新智能体、页头实时用量" width="900">
+</p>
+
+> 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
+
+---
+
+## 快速开始 — 安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+```
+
+该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。几点须知：
+
+- **先询问，后改动。** 所有系统级改动（安装软件包、下载 AI CLI）都会先征求确认；结束时的菜单可选择：直接在本终端运行、安装为后台服务（systemd/launchd，开机自启），或暂不启动。不选就不会有任何后台进程。
+- **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。也可以使用 `install.sh update` 与 `install.sh uninstall`。
+- **CI / 无终端环境：** 没有终端时，涉及系统改动的步骤会带着说明中止，而不是静默执行；在自动化场景设置 `CODEMAN_NONINTERACTIVE=1` 即可批准这些步骤。
+
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)（任意组合均可）。安装器会自动检测这四个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
+
+```bash
+codeman web
+# 打开 http://localhost:3000，开启你的第一个会话
+```
+
+**想和小团队共用一台？** 改用多用户模式启动：每人拥有自己的登录与工作空间。
+
+```bash
+codeman users add alice --admin      # 创建第一个管理员账号
+codeman web --multiuser              # 命名登录 + 按用户隔离的案例空间
+```
+
+详见下文[多用户模式](#多用户模式可选启用)。
+
+<details>
+<summary><strong>作为后台服务运行</strong></summary>
+
+安装器结尾的菜单（选项 2）可以帮你完成这一步，并在宣告成功前校验服务确实已启动。如需手动配置：
+
+**Linux（systemd）：**
+
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/codeman-web.service << EOF
+[Unit]
+Description=Codeman Web Server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now codeman-web
+loginctl enable-linger $USER
+```
+
+**macOS（launchd）：**
+
+```bash
+mkdir -p ~/Library/LaunchAgents
+cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.codeman.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$(which node)</string>
+    <string>$HOME/.codeman/app/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
+```
+
+</details>
+
+<details>
+<summary><strong>Windows（WSL）</strong></summary>
+
+```powershell
+wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+```
+
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+
+</details>
+
+---
+
+## 使用 Codeman —— 人类操作指南
+
+从头到尾走一遍如何在浏览器里驾驭 Codeman。如果你刚装好，就从这里开始。
+
+### 1. 启动服务器
+
+```bash
+codeman web                       # localhost:3000（仅环回 —— 安全默认值）
+codeman web --port 8080           # 自定义端口（或设置 CODEMAN_PORT）
+codeman web --https               # 自签名 TLS（仅远程访问时需要）
+codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_PASSWORD（见「安全」）
+```
+
+打开打印出的 URL。整个页面是一个单一仪表盘；下面的一切都在这里完成。
+
+### 2. 创建你的第一个会话
+
+点击 **+ New Session**（或 **Quick Start**）。一个会话就是一个运行在自己 tmux 终端里的 AI CLI。你可以选择：
+
+| 字段                   | 作用                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。                           |
+| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Gemini` 或 `Terminal`（普通 shell）。               |
+| **模型**               | 每会话模型（App Settings → Claude Model）。软默认值 —— 会话内 `/model` 依然有效。           |
+| **Effort / Ultracode** | 推理力度（`low`–`max`），或用 `ultracode` 开启动态多智能体工作流。随时可用 `/effort` 切换。 |
+
+点击启动 —— Codeman 通过真实 PTY 拉起 CLI，并经 SSE 流式传输到你的浏览器。
+
+### 3. 读懂仪表盘
+
+- **标签（顶部）** —— 每个会话一个。`Alt+1`–`9` 跳转，`Ctrl+Tab` 下一个，拖拽排序（标签顺序会跨设备同步）。
+- **终端（中央）** —— 真实的 `xterm.js` 终端；完整 TUI 正常渲染。直接输入并按 **Enter** 发送。`Shift+Enter` 插入换行。
+- **侧边面板** —— Respawn、Ralph、Orchestrator、Cron、Subagents、Settings（从工具栏切换）。
+
+### 4. 与智能体对话
+
+- **直接在终端输入提示** —— 即使跨越重连，输入也是精确一次送达（连接中断绝不会丢失或重复发送提示）。
+- **粘贴或拖放图片**，直接进入会话。
+- **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，自动静音停止）。
+- **附件** —— 注册外部文件/文档，并内联预览 Office/PDF。
+
+### 5. 让它自主运行
+
+| 模式             | 用途                                                                                                      | 位置                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Respawn**      | 长时间无人值守运行 —— 空闲/限额时自动重启 CLI，带自适应时序。预设：`solo-work`、`overnight-autonomous` 等 | Respawn 标签页                                                     |
+| **Ralph / Todo** | 一个自驱循环，跟踪 todo 列表并持续工作直到完成。                                                          | Ralph 标签页                                                       |
+| **Orchestrator** | 把一个目标变成分阶段计划，并跨多个智能体推动完成。                                                        | 编排器面板                                                         |
+| **Cron**         | 已保存的、命名的定时任务（`once`/`interval`/`daily`/`weekly`），到期时拉起会话并发送提示。                | ⏰ Cron 按钮（可选启用：App Settings → Display → Header Displays） |
+| **Auto-resume**  | 订阅限额重置后自动继续。                                                                                  | Respawn 标签页（顶部）                                             |
+
+### 6. 随时随地访问
+
+- **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
+- **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
+- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+
+### 7. 运维与维护
+
+- **App Settings** —— 模型、effort、权限启动模式、主题/皮肤、通知、显示开关、各 CLI 的专属选项，以及跨设备同步的自定义显示名称和按设备保存的英文/简体中文界面语言。
+- **自更新** —— git-clone 安装可在 **Settings → Updates** 中原地更新。
+- **部署你自己的改动** —— 见[开发](#开发)。
+
+> ⚠️ **安全提示：** 如果你正在 Codeman 受管会话*内部*工作（`echo $CODEMAN_MUX` → `1`），绝不要直接运行 `tmux kill-session` / `pkill claude` —— 请使用 Web UI 或 `./scripts/tmux-manager.sh`。
+
+---
+
+## 移动端优化的 Web UI
+
+在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
+
+<table>
+<tr>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
+</tr>
+<tr>
+<td align="center"><em>带二维码认证的登录页</em></td>
+<td align="center"><em>触控回答提示</em></td>
+<td align="center"><em>智能体实时工作中</em></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th>普通终端 App</th>
+<th>Codeman 移动端</th>
+</tr>
+<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
+<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
+<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
+<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
+<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
+<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
+<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
+<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
+</table>
+
+### 安全的二维码认证
+
+在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
+
+每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
+
+该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+### 触控优化界面
+
+<p align="center">
+  <img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="560">
+</p>
+
+- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮。破坏性命令（`/clear`、`/compact`）需双击确认 —— 第一次点击「上膛」，第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
+- **独立的 Enter 按钮** —— 在触控键盘上提交是高频操作，因此手机工具栏为它单独设了一个按钮。它会以按键的方式回放，从而先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上。启动 Shell 这类低频操作则移入 Run 下拉菜单（`Terminal / Shell`）
+- **滑动导航** —— 在终端上左右滑动切换会话（阈值 80px，300ms）
+- **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移（使用 `visualViewport` API，并对 iOS 地址栏漂移设置 100px 阈值）
+- **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
+- **44px 触控目标** —— 所有按钮均满足 iOS 人机界面指南的最小尺寸
+- **底部抽屉式 case 选择器** —— 用上滑模态框替代桌面端下拉菜单
+- **原生惯性滚动** —— `-webkit-overflow-scrolling: touch`，丝滑流畅
+
+```bash
+codeman web --https
+# 在手机上打开：https://<你的IP>:3000
+```
+
+> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
+
+---
+
+## 实时智能体可视化
+
+实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
+
+<p align="center">
+  <img src="docs/images/subagent-windows-20260724.png" alt="子智能体可视化 —— 三个并行 Explore 智能体的浮动窗口与实时工具调用日志" width="900">
+</p>
+
+- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
+- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
+- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
+- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
+- **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
+
+多智能体 Workflow 运行（「ultracode」）同样可视化：一个浮动运行窗口实时跟踪整个工作流，展示阶段、各智能体的 token 用量与当前工具：
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode 工作流可视化 —— 实时运行窗口，含各智能体 token 与阶段" width="900">
+</p>
+
+**智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
+
+---
+
+## 零延迟输入叠加层
+
+<p align="center">
+  <img src="docs/images/zerolag-demo.gif" alt="Zerolag 演示 —— 本地回显与服务端回显并排对比" width="900">
+</p>
+
+远程访问你的编程智能体时（VPN、Tailscale、SSH 隧道），每次按键通常需要 200–300 毫秒往返。Codeman 实现了一套**受 Mosh 启发的本地回显系统**，无论延迟多高，打字都感觉即时。
+
+xterm.js 内部一个像素级精准的 DOM 叠加层以 0ms 渲染按键。后台转发会以 50ms 防抖批次静默地把每个字符送往 PTY，因此 Tab 补全、`Ctrl+R` 历史搜索以及所有 shell 特性都正常工作。当服务端回显在 200–300ms 后到达时，叠加层无缝消失、真实终端文本接管 —— 整个切换过程不可见。
+
+- **抗 Ink 架构** —— 它作为 `.xterm-screen` 内 z-index 7 的一个 `<span>` 存在，完全不受 Ink 持续重绘屏幕的影响（此前两次使用 `terminal.write()` 的尝试都失败了，因为 Ink 会破坏注入的缓冲区内容）
+- **字体匹配渲染** —— 从 xterm.js 的计算样式读取 `fontFamily`、`fontSize`、`fontWeight` 与 `letterSpacing`，使叠加层文本与真实终端输出在视觉上无法区分
+- **完整编辑** —— 退格、重打、粘贴（多字符）、光标跟踪，输入超过终端宽度时多行换行
+- **重连后持久** —— 未发送的输入通过 localStorage 在页面刷新后保留
+- **默认启用** —— 桌面端与移动端均可用，会话空闲或繁忙时都生效
+
+> 已抽取为独立库：[`xterm-zerolag-input`](https://www.npmjs.com/package/xterm-zerolag-input) —— 见[已发布的包](#已发布的包)。
+
+---
+
+## 重生控制器（Respawn Controller）
+
+自主工作的核心。当智能体进入空闲，重生控制器会检测到，发送继续提示，循环执行上下文管理命令以获得全新上下文，然后恢复工作 —— 可完全无人值守运行 **24 小时以上**。
+
+```
+WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE → WATCHING
+```
+
+- **多层空闲检测** —— 完成消息、AI 驱动的空闲检查、输出静默、token 稳定性
+- **用量限额自动恢复**（_可选，默认关闭_）—— 当 Claude 因订阅用量限额而停止（"You've hit your limit · resets 3pm"）时，Codeman 会解析重置时间，等到限额刷新（外加 2 分钟安全缓冲）后自动关闭限额对话框并发送 `continue`，让通宵任务平稳跨过 5 小时窗口而不是停摆到早晨。可识别 Claude Code 各版本的全部限额消息格式；若仍受限会自动重试；计划在 Codeman 重启后依然生效；暂停期间会阻止重生循环，避免 `/clear` 清掉等待中的对话。在会话 Respawn 标签页顶部按会话启用
+- **熔断器** —— 当 Claude 卡住时防止重生抖动（CLOSED → HALF_OPEN → OPEN 状态，跟踪连续无进展与重复错误）
+- **健康评分** —— 0–100 健康分，分项涵盖循环成功率、熔断器状态、迭代进展与卡死恢复
+- **内置预设** —— `solo-work`（3s 空闲，60min）、`subagent-workflow`（45s，240min）、`team-lead`（90s，480min）、`ralph-todo`（8s，480min）、`overnight-autonomous`（10s，480min）
+
+---
+
+## 编排器循环（Orchestrator Loop）
+
+超越单会话重生，**编排器**把一个高层目标转化为分阶段计划，并跨多个智能体推动其完成 —— 这是一个运行 `idle → planning → approval → executing → verifying → (replanning) → completed` 的状态机。
+
+- **先规划，后执行** —— 从你的目标生成分阶段计划，并在动手前暂停等待审批；可带反馈拒绝以重新生成
+- **逐阶段验证关卡** —— 每个阶段在下一阶段开始前都会被验证；失败时编排器会重新规划而非一头扎下去
+- **多智能体执行** —— 将各阶段分发给团队智能体 / 任务队列，协调超出单会话能力的工作
+- **崩溃安全** —— 完整状态持久化在 `state.json` 的 `orchestrator` 键下，可在重启后存续
+- **可从 UI 或 API 驱动** —— 编排器面板，或 `POST /api/orchestrator/start` → `/approve` → `/status`（共 10 个端点）
+
+> 与 Ralph（单会话自主循环）不同：编排器协调多阶段、多智能体执行。完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
+
+---
+
+## 多会话仪表盘
+
+运行 **20 个并行会话**且全程可见 —— 60fps 的实时 xterm.js 终端、按会话的 token 与成本跟踪、基于标签的导航，以及一键管理。
+
+<p align="center">
+  <img src="docs/screenshots/multi-session-dashboard.png" alt="多会话仪表盘" width="800">
+</p>
+
+### 持久化会话
+
+每个会话都运行在 **tmux** 内 —— 会话可在服务器重启、网络中断与机器休眠后存续。启动时自动恢复，具备双重冗余。幽灵会话发现机制能找到孤立的 tmux 会话。受管会话带有环境标签，因此智能体不会杀掉自己的会话。
+
+### 会话管理器与命令面板
+
+`Ctrl/Cmd/Alt+K` 打开模糊搜索的会话面板；**Browse all sessions** 打开会话管理器：一份去重后的完整清单，涵盖 Codeman 所知的一切（活动会话、来自状态与生命周期历史的既往会话，以及 Claude 转录），每一行都显示其第一条与最近一条提示。
+
+- **置顶（Pin）**：把会话固定到列表顶部。被置顶的会话甚至能挺过被杀掉（降级为一条轻量的已停止记录，依然可见、可恢复）。
+- **名称保留**：从会话管理器恢复既往会话时保留其原有名称，而不是生成一个新名称。
+- **跨设备标签顺序**：拖拽排序的标签顺序保存在服务端，你的排列会从桌面跟随到手机。
+
+### 主机名感知的窗口标题
+
+在多台主机上运行 Codeman（笔记本、开发机、NAS）？浏览器标签标题是 `codeman:<主机名>`，让你无需点进去就能分辨每个标签对应哪个后端：
+
+```bash
+codeman web                                # codeman:<os.hostname()>
+codeman web --title-hostname dev-box       # codeman:dev-box（用于覆盖嘈杂的主机名）
+```
+
+标题在首字节时就被模板化进所提供的 HTML 中，因此从第一帧绘制起就是正确的，且无需 JavaScript 也能工作。同样的主机名前缀也应用于标签闪烁格式（`⚠️ (N) codeman:<host>`）和操作系统级桌面通知（`codeman:<host>: <事件>`），让系统通知中心里的跨主机提醒也不再含糊。
+
+### 智能 Token 管理
+
+| 阈值            | 动作            | 结果                   |
+| --------------- | --------------- | ---------------------- |
+| **110k tokens** | 自动 `/compact` | 上下文被摘要，工作继续 |
+| **140k tokens** | 自动 `/clear`   | 以 `/init` 全新开始    |
+
+### 通知
+
+当会话需要关注时实时桌面提醒 —— `permission_prompt` 与 `elicitation_dialog` 触发关键的红色标签闪烁，`idle_prompt` 触发黄色闪烁。点击任意通知即可直接跳转到相关会话。Hook 按 case 目录自动配置。
+
+### Ralph / Todo 跟踪
+
+自动检测 Ralph 循环、`<promise>` 标签、TodoWrite 进度（`4/9 complete`）以及迭代计数器（`[5/50]`），并提供实时进度环与已用时间跟踪。
+
+<p align="center">
+  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph 循环跟踪" width="800">
+</p>
+
+### 运行摘要（Run Summary）
+
+点击任意会话标签上的图表图标，即可看到所发生一切的时间线 —— 重生周期、token 里程碑、自动 compact 触发、空闲/工作切换、hook 事件、错误等等。
+
+### 零闪烁终端
+
+基于终端的 AI 智能体（Claude Code 的 Ink、OpenCode 的 Bubble Tea）会在每次状态变更时重绘屏幕。Codeman 实现了一套 6 层抗闪烁流水线，让所有会话都获得平滑的 60fps 输出：
+
+```
+PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端 rAF → xterm.js（60fps）
+```
+
+---
+
+## 更多特性
+
+- **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex** 或 **Gemini**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Docker 会话** —— 在隔离且加固的容器中运行案例。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一案例的多个会话共享一个容器；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
+- **远程 SSH 会话**：把案例指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
+- **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
+- **语音输入** —— 用 Deepgram Nova-3 口述提示（带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
+- **图像输入** —— 直接把图片粘贴或拖放进会话
+- **手势控制** _(可选)_ —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Display 启用
+- **多显示器横跨** _(macOS)_ —— 一键打开一个横跨所有显示器最大化的浏览器窗口，让浮动的智能体/手势面板可以跨越物理拼接缝
+- **文件查看器按钮** _(可选)_ —— 头部新增一个按钮，一键切换内置文件浏览器面板；在 App Settings → Display → Header Displays 中启用
+- **CJK / 输入法支持** —— 完整支持中文 / 日文 / 韩文的组合输入
+- **操作系统通知与主机名感知标题** —— 桌面提醒与标签标题以 `codeman:<host>` 为前缀，使多主机配置不再含糊
+
+---
+
+## 隔离的 Docker 会话
+
+让案例（case）运行在专属的加固 Docker 容器里，而不是直接跑在主机上：获得安全隔离、可复现的工具链和一键可移植性。
+
+- **一键启动** —— 在 **New Case → Create New** 中勾选 **🐳 Run in an isolated Docker container**。Codeman 会创建案例文件夹、用默认设置启动容器，并在容器内启动智能体。无需填写任何主机/镜像/网络字段。
+- **资源模板** —— 展开复选框可选 **Small / Medium / Large / GPU** 预设（内存、CPU、GPU），也可以完全自定义。**磁盘是弹性的** —— 存储随数据增长，没有固定上限。
+- **按案例共享容器** —— 多个会话可以 `docker exec` 进同一个容器；结束某个会话绝不会影响其他会话所在的容器。
+- **默认加固** —— 非 root、`--cap-drop ALL`、`no-new-privileges`、PID/内存上限，绝不使用 `--privileged` 或 docker socket；**密封（sealed）** 配置（不注入主机凭据、关闭网络）只需一个开关。
+- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Gemini / OpenCode 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
+- **迁移到另一台机器** —— 把容器的完整环境（工具链 + 工作区）导出为可移植的 `.tar.gz`，在另一台机器上导入到新案例即可继续。
+- **持久耐用** —— Codeman 重启后重连会回到同一个存活的智能体；容器停止/重启后则从绑定挂载的转录恢复对话。
+
+前置条件：只需 Docker（或 Podman）。智能体基础镜像会在首次使用时自动构建，构建进度实时显示在 UI 中（也可用 `node scripts/build-agent-image.mjs` 预构建）。完整指南：[`docs/docker-cases.md`](docs/docker-cases.md)。
+
+---
+
+## 远程 SSH 会话
+
+把案例（case）指向另一台机器，通过 SSH 让智能体**在那台机器上**运行，同时保留同样的仪表盘、移动端 UI 与自主运行特性。你的笔记本只是一扇窗口，会话本体活在远程主机上。
+
+- **天生持久**：智能体运行在远程主机上一个专用的 tmux 会话里，SSH 断连、网络切换或笔记本休眠都不会中断任务。重新连接后回到同一个活跃对话。
+- **自动重连**：一个带上限退避的监视器发现 SSH 面板断开后，会静默重新附着到仍在运行的远程会话（设置中有总开关；主动杀掉的会话绝不会被复活）。
+- **发现与附着**：列出主机上已在运行的 `codeman-*` 会话（由那台机器自己的 Codeman 或其他操作者启动）并附着其一。非你所有的已附着会话在关闭标签时**只分离，绝不杀掉**。
+- **共享会话**：多个客户端可以以不同窗口尺寸同时附着同一个远程会话而互不挤压；发现列表会显示带客户端计数的「shared」徽标。
+- **注入安全**：所有 ssh 命令行都经由单一的 shell 转义构建器生成，主机/路径/身份文件字段均有模式校验。
+
+在 **New Case → Remote** 中配置（主机、用户、身份文件、可选跳板机）。完整设计：[`docs/remote-sessions.md`](docs/remote-sessions.md)。
+
+---
+
+## 多用户模式（可选启用）
+
+与一个小型互信团队共享同一个 Codeman，每人拥有自己的登录与工作空间。**默认关闭**：不加该开关时，行为与单用户完全一致。
+
+用 `codeman web --multiuser`（或 `CODEMAN_MULTIUSER=1`）启用。创建第一个管理员后，可通过 CLI 或 App Settings 中的 **Users** 标签页管理用户：
+
+```bash
+codeman users add alice --admin      # 提示输入密码（或 --password-stdin）
+codeman users add bob                # 普通用户
+codeman users list
+```
+
+- **按用户的空间**：每个用户的案例位于 `~/codeman-users/<name>/cases`；会话、案例、搜索与实时事件都按属主隔离。管理员可以看到全部。
+- **可单独吊销的登录**：命名用户的密码以 scrypt 哈希保存在 `~/.codeman/users.json`；可随时禁用、重置（一次性密码）或删除账号。管理员操作审计记录在 `~/.codeman/admin-audit.jsonl`。
+- **普通用户的更安全默认值**：非管理员以 `--permission-mode auto` 运行 Claude（Anthropic 的分类器护栏模式）；raw shell 会话、cron `launchCommand` 与跳过权限模式需要按用户显式授权。
+
+> ⚠️ **这只是工作空间的划分，不是用户之间的沙箱。** 所有会话都以同一个操作系统账户运行，因此有心用户的智能体依然能触及他人的文件。若需要真正的隔离，请结合 **Docker 案例**，或在不同的操作系统账户下运行独立实例。参见 [`docs/multi-user-plan.md`](docs/multi-user-plan.md) 与 [`docs/security-architecture.md`](docs/security-architecture.md) 的多用户章节。
+
+---
+
+## 远程访问 —— Cloudflare 隧道
+
+使用免费的 [Cloudflare 快速隧道](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)，从手机或本地网络外的任意设备访问 Codeman —— 无需端口转发、无需 DNS、无需静态 IP。
+
+```
+浏览器（手机/平板）→ Cloudflare 边缘（HTTPS）→ cloudflared → localhost:3000
+```
+
+**前置条件：** 安装 [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 并在环境中设置 `CODEMAN_PASSWORD`。
+
+```bash
+# 快速开始
+./scripts/tunnel.sh start      # 启动隧道，打印公网 URL
+./scripts/tunnel.sh url        # 显示当前 URL
+./scripts/tunnel.sh stop       # 停止隧道
+./scripts/tunnel.sh status     # 服务状态 + URL
+```
+
+脚本会在首次运行时自动安装一个 systemd 用户服务。隧道 URL 是一个随机生成的 `*.trycloudflare.com` 地址，每次隧道重启都会改变。
+
+<details>
+<summary><strong>持久隧道（重启后存续）</strong></summary>
+
+```bash
+# 启用为持久服务
+systemctl --user enable codeman-tunnel
+loginctl enable-linger $USER
+
+# 或通过 Codeman Web UI：Settings → Tunnel → 切换为开
+```
+
+</details>
+
+<details>
+<summary><strong>认证</strong></summary>
+
+1. 首次请求 → 浏览器弹出 Basic Auth 提示（用户名：`admin` 或 `CODEMAN_USERNAME`）
+2. 成功后 → 服务端签发 `codeman_session` cookie（24 小时 TTL，活动时自动延长）
+3. 后续请求通过 cookie 静默认证
+4. 同一 IP 失败 10 次 → 429 速率限制（15 分钟衰减）
+
+通过隧道暴露前**务必设置 `CODEMAN_PASSWORD`** —— 否则任何拿到 URL 的人都能完全访问你的会话。
+
+</details>
+
+### 二维码认证
+
+在手机键盘上输密码很糟糕。Codeman 用**短暂的一次性二维码令牌**解决这个问题 —— 扫描桌面上的二维码，手机即刻完成认证。无密码提示、无打字、无剪贴板。
+
+```
+桌面显示二维码  →  手机扫描  →  GET /q/Xk9mQ3  →  服务端校验
+→  令牌原子性消费（一次性）  →  签发会话 cookie  →  302 跳转到 /
+→  桌面收到通知：「设备已通过二维码认证」  →  自动生成新二维码
+```
+
+只拿到裸隧道 URL（没有二维码）的人，仍会撞上标准密码提示。二维码是快速通道；密码是回退方案。
+
+#### 工作原理
+
+服务端维护一个轮换的、短生命周期、一次性令牌池。每个令牌由一个 256 位密钥（`crypto.randomBytes(32)`）和一个用作 URL 路径中不透明查找键的 6 字符 base62 短码配对组成。二维码编码的 URL 形如 `https://abc-xyz.trycloudflare.com/q/Xk9mQ3` —— 短码是指针，而非密钥本身，因此它绝不会通过浏览器历史、`Referer` 头或 Cloudflare 边缘日志泄露。
+
+每 **60 秒**，服务端自动轮换到一个全新令牌。上一个令牌会保留 **90 秒的宽限期**，以处理你刚好在轮换瞬间扫描的竞争情况 —— 此后即作废。每个令牌都是**一次性**的：手机一旦成功扫描，令牌就被原子性消费，并立即为桌面显示生成一个新的。
+
+#### 安全设计
+
+该设计参考了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025），该研究发现 Top-100 网站中有 47 个因横跨 42 个 CVE 的 6 个关键设计缺陷而易受二维码认证攻击。Codeman 全部六个都做了应对：
+
+| USENIX 缺陷                  | 缓解措施                                                                                      |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| **缺陷 1**：缺少一次性强制   | 令牌首次扫描即原子性消费 —— 重放永远失败                                                      |
+| **缺陷 2**：长生命周期令牌   | 60s TTL + 90s 宽限，由定时器自动轮换                                                          |
+| **缺陷 3**：可预测的令牌生成 | `crypto.randomBytes(32)` —— 256 位熵。短码采用拒绝采样以消除取模偏差                          |
+| **缺陷 4**：客户端令牌生成   | 仅服务端 —— 令牌在嵌入二维码前绝不离开服务器                                                  |
+| **缺陷 5**：缺少状态通知     | 桌面提示：_「设备 [IP] 已通过二维码认证（Safari）。不是你？[吊销]」_ —— 实时 QRLjacking 检测  |
+| **缺陷 6**：会话绑定不足     | 存储 IP + User-Agent 以供审计。通过 API 手动吊销会话。HttpOnly + Secure + SameSite=lax cookie |
+
+#### 时序安全的查找
+
+短码存储在 `Map<shortCode, TokenRecord>` 中。校验使用 `Map.get()` —— 一个基于哈希的 O(1) 查找，不会通过响应时延泄露目标字符串的任何信息。热路径上任何地方都没有逐字符字符串比较，彻底消除了时序侧信道攻击。
+
+#### 速率限制（双层）
+
+二维码认证有自己的速率限制，与密码认证完全独立：
+
+- **按 IP**：同一 IP 失败 10 次二维码尝试即触发 429 封锁（15 分钟衰减窗口）—— 与 Basic Auth 的失败计数器分开，因此打错密码不会消耗你的二维码额度
+- **全局**：所有 IP 合计每分钟 30 次二维码尝试 —— 抵御分布式暴力破解。考虑到 62^6 = 568 亿种可能短码、任意时刻仅约 2 个有效，无论如何暴力破解都在计算上不可行
+
+#### 二维码尺寸优化
+
+URL 被刻意保持精简（`/q/` 路径 + 6 字符码 ≈ 53–56 个字符），以瞄准 **QR 版本 4**（33×33 模块）而非版本 5（37×37）。更小的二维码在低端手机上扫描更快 —— 现代设备读取版本 4 仅需 100–300 毫秒。`/q/` 前缀相比 `/qr-auth/` 省下 7 个字节，仅此一项就足以决定二维码版本的差别。
+
+#### 桌面体验
+
+二维码显示每 60 秒通过 SSE 自动刷新，SVG 直接嵌入事件载荷（约 2–5KB）—— 无需额外 HTTP 请求，刷新低于 50ms。倒计时器显示剩余时间。「重新生成」按钮可即时使所有现有令牌失效并创建一个新的（在你怀疑二维码被拍照时很有用）。
+
+当有人通过二维码认证时，桌面会弹出一个带设备 IP 与浏览器信息的通知 —— 如果不是你，一键即可吊销所有会话。
+
+#### 威胁覆盖
+
+| 威胁                    | 为何无效                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| **二维码截图被分享**    | 一次性：首次扫描即消费。60s TTL：攻击者动手前已过期。桌面通知会立即提醒你。          |
+| **重放攻击**            | 原子性一次性消费 + 60s TTL。旧 URL 始终返回 401。                                    |
+| **Cloudflare 边缘日志** | 短码是不透明的 6 字符查找键，而非真正的 256 位令牌。一次性意味着从日志重放永远失败。 |
+| **暴力破解**            | 568 亿种组合、任意时刻约 2 个有效、双层速率限制，早在统计可行性之前就已拦截。        |
+| **QRLjacking**          | 60s 轮换迫使实时转发。桌面提示提供即时检测。自托管单用户场景使钓鱼难以成立。         |
+| **时序攻击**            | 基于哈希的 Map 查找 —— 无字符串比较时序泄露。                                        |
+| **会话 cookie 窃取**    | HttpOnly + Secure + SameSite=lax + 24h TTL。可在 `POST /api/auth/revoke` 手动吊销。  |
+
+#### 横向对比
+
+| 平台             | 模型                                                                                   | 对比                                                                                                                                                     |
+| ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Discord**      | 长生命周期令牌、无确认、[屡被利用](https://owasp.org/www-community/attacks/Qrljacking) | Codeman：一次性 + TTL + 通知                                                                                                                             |
+| **WhatsApp Web** | 手机确认「关联设备？」，约 60s 轮换                                                    | 轮换相当；WhatsApp 额外加了显式确认（对单用户而言是可接受的取舍）                                                                                        |
+| **Signal**       | 临时公钥、端到端加密信道                                                               | 加密更强，但 [2025 年仍被俄罗斯国家级行为者](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger)通过社会工程攻破 |
+
+> 完整设计理由、安全分析与实现细节：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+---
+
+## 安全
+
+Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。（启动权限模式可配置，见下文。）近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。**发现了漏洞？** 私下披露方式与已知限制清单见 [`SECURITY.md`](.github/SECURITY.md)。
+
+### 网络与访问
+
+- **默认仅环回** —— 绑定 `127.0.0.1`，仅可从本机访问，因此「无密码」默认配置开箱即安全。在未设置 `CODEMAN_PASSWORD` 的情况下绑定非环回主机会*启动但打印一条醒目警告*，并给出三个具体修复方案（设置密码、环回 + 一个带认证的隧道，或用 `--allow-unauthenticated-network` 显式确认）
+- **可选认证，真实会话** —— 通过 `CODEMAN_USERNAME`（默认 `admin`）/ `CODEMAN_PASSWORD` 的 HTTP Basic 认证。成功后签发一个不透明的 256 位 `codeman_session` cookie（`randomBytes(32)`）—— 服务端校验，而非客户端签名，因此无法离线伪造（24h TTL、自动延长、设备上下文审计日志）
+- **按 IP 速率限制** —— 失败 10 次 → `429` 并带 `Retry-After`（15 分钟衰减）。即便攻击者在同一 IP 上猛攻，有效 cookie 或正确密码也能*立即*恢复 —— 这很重要，因为所有隧道流量共享同一个环回 IP。二维码认证有自己独立的限制器
+- **可配置的权限模式**：`--dangerously-skip-permissions` 只是默认值。**App Settings → Claude CLI → Startup Mode** 可以把新会话切换为 Anthropic 的分类器护栏 `auto` 模式（低打扰，需要 Claude Code 2.1.207+）、`normal` 提示模式，或一份显式的允许工具列表。多用户模式下，未获授权的用户会被强制为 `auto`，shell 会话与跳过权限需要按用户显式授权
+
+### 始终开启的浏览器加固（v0.9.5）
+
+以下对**每个**请求都生效 —— 在认证之前，即便是默认的无密码环回安装：
+
+- **Host 头允许列表 → 阻断 DNS 重绑定。** 一个被重绑定到 `127.0.0.1` 的自定义域名会在任何处理器运行前被 `403 host not allowed` 拒绝。允许：`localhost`、任意 IP 字面量、绑定主机、`.ts.net` / `.trycloudflare.com` / `.cfargotunnel.com`、当前受管隧道，以及 `CODEMAN_ALLOWED_HOSTS`（在此添加自定义反向代理域名 —— 逗号分隔；精确主机或前导点 `.suffix` 匹配子域名）
+- **跨站 Origin / CSRF 防护。** 对变更状态的方法（`POST`/`PUT`/`PATCH`/`DELETE`），`Origin` 必须通过同一允许列表，否则返回 `403 cross-site request blocked`。*缺失*的 Origin 被允许（因此 `curl`、CLI 与 Claude Code hook 仍可工作）；只有存在但外来、或不透明的 `null` origin 才会被拒绝
+- **原始 `text/plain` 请求体。** 全局解析器不再对 `text/plain` 做 JSON 解析，封堵了那个跨站 `fetch` 能在无预检的情况下把 JSON 走私进写路由的 CORS「简单请求」CSRF 向量
+- **WebSocket Origin 校验。** 终端 WS 升级运行同样的 Host + Origin 检查，失败时以代码 `4003` 关闭（反 CSWSH）
+- **XSS 转义的智能体输出。** AI 衍生的字符串（工具名、命令参数、子智能体描述）在渲染进子智能体 / 活动面板前，于每个注入点都做 HTML 转义
+
+### 输入、文件与响应头
+
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
+- **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 50 MB 原始与下载；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
+- **安全响应头** —— `Content-Security-Policy`（`default-src 'self'`，每个例外都逐条列举）、`X-Content-Type-Options: nosniff`、`X-Frame-Options: SAMEORIGIN`、HTTPS 下的 HSTS，以及**仅**对 `localhost` / `127.0.0.1` / `::1` 反射的 CORS
+
+### 供应链与隔离
+
+- **锁定并校验的依赖** —— 安全敏感的传递依赖通过 npm `overrides` 强制为已打补丁版本；每次提交/PR 都检查锁文件完整性（所有条目都解析到 `registry.npmjs.org` 且带 `sha512` 哈希）。公共资源在 CI 中做 NUL 字节扫描与 `node --check` 校验
+- **多实例隔离** —— `CODEMAN_INSTANCE` 同时限定 tmux 套接字（`-L codeman-<name>`）与数据目录（`~/.codeman-<name>`），因此两个实例绝不会互相附着对方的活动会话
+
+> 移动端登录使用一次性、60 秒二维码令牌 —— 完整设计见上文[二维码认证](#二维码认证)（它应对了 USENIX Security 2025 二维码登录研究中的全部 6 个缺陷）。
+
+---
+
+## SSH 替代方案（`sc`）
+
+如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
+
+```bash
+sc              # 交互式选择器
+sc 2            # 快速附着到会话 2
+sc -l           # 列出会话
+```
+
+单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
+
+---
+
+## 键盘快捷键
+
+> Ctrl 绑定在 macOS 上也接受 Cmd。
+
+| 快捷键                          | 动作                                                     |
+| ------------------------------- | -------------------------------------------------------- |
+| `Ctrl/Cmd+W`                    | 杀掉当前会话                                             |
+| `Ctrl/Cmd/Option+K`             | 查找已打开的会话或新建一个                               |
+| `Ctrl/Cmd+Tab`                  | 下一个会话                                               |
+| `Alt/Option+[` / `Alt/Option+]` | 上一个 / 下一个会话                                      |
+| `Alt/Option+1`–`Alt/Option+9`   | 切换到第 N 个标签（按物理键位，macOS Option 布局也适用） |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移                                    |
+| `Ctrl/Cmd+L`                    | 清屏                                                     |
+| `Ctrl+Shift+R`                  | 恢复终端尺寸                                             |
+| `Ctrl+Shift+V`                  | 切换语音输入                                             |
+| `Ctrl/Cmd +` / `-`              | 字体大小                                                 |
+| `Ctrl/Cmd+?`                    | 键盘帮助                                                 |
+| `Shift+Enter`                   | 插入换行（发送到终端）                                   |
+| `Escape`                        | 关闭面板与模态框                                         |
+
+---
+
+## 从智能体驱动 Codeman —— 编程指南
+
+面向不经浏览器控制 Codeman 的 AI 智能体与自动化：一个拉起工作会话的智能体、一个 CI 机器人，或是**运行在 Codeman 会话*内部*、编排其他会话的 Claude Code**。UI 能做的一切都是 HTTP + CLI，因此智能体也能做。
+
+### 检测自己身处 Codeman 内部
+
+当 CLI 运行在 Codeman 受管会话中时，以下环境变量会被设置 —— 读取它们，别硬编码任何东西：
+
+| 变量                       | 含义                                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `CODEMAN_MUX=1`            | 你在一个受管 tmux 会话里。**绝不要** `tmux kill-session` / `pkill claude` / `pkill tmux` —— 你会杀掉自己或兄弟会话。 |
+| `CODEMAN_API_URL`          | API 的基础 URL（例如 `https://127.0.0.1:3000`）。下面每个调用都用它。                                                |
+| `CODEMAN_SESSION_ID`       | *你自己的*会话 id。用它避免对自己下手。                                                                              |
+| `CODEMAN_HOOK_SECRET_FILE` | hook 密钥文件的路径（受管隧道开启时调用 `/api/hook-event` 必需）。                                                   |
+
+### 行路规则（POST 之前先读）
+
+1. **只发单行输入。** 编程输入会作为字面文本 **+ Enter** 一次性发送。多行字符串会破坏智能体 TUI（Ink）—— 发送一行，或拆成多次调用。
+2. **让输入幂等。** 在 `POST …/input` 上带上稳定的 `clientId` 和按会话单调递增的 `seq`。服务端会去重，因此连接中断后的重试不会重复投递提示。
+3. **认证。** 若设置了 `CODEMAN_PASSWORD`，发送 HTTP Basic 认证（用户 `admin` 或 `CODEMAN_USERNAME`）或 `codeman_session` cookie。默认的环回安装无密码。缺失的 `Origin` 头被允许，因此普通 `curl` 可用；跨站的浏览器 origin 会被拒绝（CSRF 防护）。
+4. **响应信封。** 多数端点返回 `{ "success": true, "data": … }`（错误：`{ "success": false, "error", "errorCode" }`）。少数遗留 GET 返回裸响应体 —— **两种都要处理**（`body.data ?? body`）。
+5. **`/api/v1/*`** 是 `/api/*` 的稳定别名。
+
+### 常用配方
+
+```bash
+API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
+# （若设置了密码，给每个调用加上  -u admin:"$CODEMAN_PASSWORD"）
+
+# 1. 看看有什么在运行
+curl -s "$API/api/sessions" | jq '.data // .'
+
+# 2. 拉起一个工作会话（「case」= 命名工作目录）
+curl -s -X POST "$API/api/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
+
+# 3. 向会话发送提示（精确一次：clientId + seq）
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+
+# 4. 读回终端内容
+curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+
+# 5. 流式接收实时事件（会话输出、智能体活动、状态）
+curl -sN "$API/api/events"          # Server-Sent Events
+
+# 6. 调度周期性工作（cron 风格任务）
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
+       "promptMode":"inline_text","promptText":"Update dependencies and open a PR",
+       "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
+       "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
+
+# 7. 查看后台子智能体及其活动记录
+curl -s "$API/api/subagents" | jq '.data // .'
+curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
+
+# 8. 全系统快照（会话、设置、重生、统计）
+curl -s "$API/api/status" | jq
+```
+
+### 或使用内置 CLI
+
+同样的操作也有命令形式（`codeman <cmd>`，括号内为别名）—— 在会话内的 shell 工具里很顺手：
+
+```bash
+codeman session start -d /path/to/repo   # (s)  启动会话
+codeman session list                     #      列出会话
+codeman session logs <id>                #      查看输出
+codeman task add "fix the failing test"  # (t)  排入任务
+codeman ralph start --min-hours 8        # (r)  启动自主循环
+codeman attach <path>                    #      附着 Claude hook 上下文
+```
+
+### Hook（事件*回流*到 Codeman）
+
+Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission_prompt`、`idle_prompt`、`stop`、`task_completed` 等），让仪表盘实时响应。该端点在环回上免认证，但在受管隧道下需要 `X-Codeman-Hook-Secret` 头（从 `$CODEMAN_HOOK_SECRET_FILE` 读取）。通常你不需要手动调用它 —— Codeman 会自动接好 —— 但自主层正是靠它「看见」智能体在做什么。
+
+> 完整端点列表与请求/响应形状见下文。
+
+---
+
+## API
+
+基于 Fastify 的 REST —— **20 个路由模块中约 190 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。所有响应都使用 `ApiResponse<T>` 信封（`{success, data}` / `{success, error, errorCode}`）；`/api/v1/*` 是稳定别名。以下是一个有代表性的子集：
+
+### 会话（Sessions）
+
+| 方法     | 端点                       | 说明                                                                           |
+| -------- | -------------------------- | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/sessions`            | 列出全部                                                                       |
+| `POST`   | `/api/quick-start`         | 创建 case + 启动会话（`{caseName?, mode?, effort?, envOverrides?}`）           |
+| `POST`   | `/api/sessions/:id/input`  | 发送输入（`{input, useMux?, clientId?, seq?}` —— `clientId`+`seq` = 精确一次） |
+| `GET`    | `/api/sessions/:id/output` | 读取终端输出                                                                   |
+| `GET`    | `/api/sessions/unified`    | 统一的活动 + 历史清单（会话管理器）：`?q=&limit=`                              |
+| `POST`   | `/api/sessions/:id/pin`    | 在会话管理器中置顶 / 取消置顶（`{pinned}`）                                    |
+| `PUT`    | `/api/session-order`       | 跨设备同步标签顺序（`{order: [ids]}`）                                         |
+| `DELETE` | `/api/sessions/:id`        | 删除会话                                                                       |
+
+### 重生（Respawn）
+
+| 方法   | 端点                               | 说明                 |
+| ------ | ---------------------------------- | -------------------- |
+| `POST` | `/api/sessions/:id/respawn/enable` | 启用，带配置与定时器 |
+| `POST` | `/api/sessions/:id/respawn/stop`   | 停止控制器           |
+| `PUT`  | `/api/sessions/:id/respawn/config` | 更新配置             |
+
+### Ralph / Todo
+
+| 方法   | 端点                             | 说明                 |
+| ------ | -------------------------------- | -------------------- |
+| `GET`  | `/api/sessions/:id/ralph-state`  | 获取循环状态 + todos |
+| `POST` | `/api/sessions/:id/ralph-config` | 配置跟踪             |
+
+### 编排器（Orchestrator）
+
+| 方法   | 端点                        | 说明            |
+| ------ | --------------------------- | --------------- |
+| `POST` | `/api/orchestrator/start`   | 从目标启动编排  |
+| `POST` | `/api/orchestrator/approve` | 批准生成的计划  |
+| `GET`  | `/api/orchestrator/status`  | 当前阶段 + 进度 |
+| `POST` | `/api/orchestrator/stop`    | 停止并清理      |
+
+### Cron（定时任务）
+
+| 方法             | 端点                         | 说明                  |
+| ---------------- | ---------------------------- | --------------------- |
+| `GET` / `POST`   | `/api/cron/jobs`             | 列出 / 创建 cron 任务 |
+| `PUT` / `DELETE` | `/api/cron/jobs/:id`         | 更新 / 删除任务       |
+| `PUT`            | `/api/cron/jobs/:id/enabled` | 启用 / 禁用           |
+| `POST`           | `/api/cron/jobs/:id/run`     | 立即运行              |
+| `GET`            | `/api/cron/jobs/:id/runs`    | 运行历史              |
+
+### 子智能体（Subagents）
+
+| 方法     | 端点                            | 说明               |
+| -------- | ------------------------------- | ------------------ |
+| `GET`    | `/api/subagents`                | 列出所有后台智能体 |
+| `GET`    | `/api/subagents/:id`            | 智能体信息与状态   |
+| `GET`    | `/api/subagents/:id/transcript` | 完整活动记录       |
+| `DELETE` | `/api/subagents/:id`            | 杀掉智能体进程     |
+
+### 系统（System）
+
+| 方法   | 端点                            | 说明                                     |
+| ------ | ------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/events`                   | SSE 流                                   |
+| `GET`  | `/api/status`                   | 完整应用状态                             |
+| `POST` | `/api/hook-event`               | Hook 回调                                |
+| `GET`  | `/api/system/update/check`      | 检查新发行版                             |
+| `POST` | `/api/system/update`            | 自更新（git-clone 安装）                 |
+| `POST` | `/api/clipboard`                | 把文本推送到所有已连接浏览器（`{text}`） |
+| `GET`  | `/api/sessions/:id/run-summary` | 时间线 + 统计                            |
+
+---
+
+## 架构
+
+```mermaid
+flowchart TB
+    subgraph Codeman["CODEMAN"]
+        subgraph Frontend["前端层"]
+            UI["Web UI<br/><small>xterm.js + 智能体窗口</small>"]
+            API["REST API<br/><small>Fastify</small>"]
+            SSE["SSE 事件<br/><small>/api/events</small>"]
+        end
+
+        subgraph Core["核心层"]
+            SM["会话管理器"]
+            S1["会话 (PTY)"]
+            S2["会话 (PTY)"]
+            RC["重生控制器"]
+            ORC["编排器循环"]
+        end
+
+        subgraph Detection["检测层"]
+            RT["Ralph 跟踪器"]
+            SW["子智能体监视器<br/><small>~/.claude/projects/*/subagents</small>"]
+            TW["团队监视器<br/><small>~/.claude/teams/*</small>"]
+        end
+
+        subgraph Persistence["持久化层"]
+            SCR["Mux 管理器<br/><small>(tmux)</small>"]
+            SS["状态存储<br/><small>state.json</small>"]
+        end
+
+        subgraph External["外部"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
+            BG["后台智能体<br/><small>(Task 工具)</small>"]
+        end
+    end
+
+    UI <--> API
+    API <--> SSE
+    API --> SM
+    SM --> S1
+    SM --> S2
+    SM --> RC
+    SM --> ORC
+    SM --> SS
+    S1 --> RT
+    S1 --> SCR
+    S2 --> SCR
+    RC --> SCR
+    ORC --> SCR
+    SCR --> CLI
+    SW --> BG
+    SW --> SSE
+    TW --> SSE
+```
+
+---
+
+## 开发
+
+```bash
+npm install
+npx tsx src/index.ts web    # 开发模式
+npm run build               # 生产构建
+npm run test:ci             # 运行测试（CI 套件；浏览器套件需要额外环境）
+```
+
+完整文档见 [CLAUDE.md](./CLAUDE.md)。
+
+---
+
+## 代码库质量
+
+本代码库经历了一次全面的 7 阶段重构，消除了上帝对象、集中了配置，并建立了模块化架构：
+
+| 阶段             | 改了什么                                                                                                      | 影响                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **性能**         | 缓存端点、SSE 自适应批处理、缓冲区分块                                                                        | 终端延迟低于 16ms                          |
+| **路由抽取**     | `server.ts` 拆分为 15 个领域路由模块 + 认证中间件 + 端口接口                                                  | server.ts 代码量 **−67%**（6,736 → 2,254） |
+| **领域拆分**     | `types.ts` → 16 个领域文件、`ralph-tracker` → 7 个文件、`respawn-controller` → 5 个文件、`session` → 6 个文件 | 不再有上帝文件                             |
+| **前端模块**     | `app.js` → 18 个抽取模块，横跨基础设施、领域与特性层                                                          | app.js 核心降至 **约 3.4K 行**             |
+| **配置合并**     | 约 70 个散落的魔法数字 → 10 个领域聚焦的配置文件                                                              | 零跨文件重复                               |
+| **测试基础设施** | 共享 mock 库、12 个路由测试文件、统一的 MockSession                                                           | 路由处理器可通过 `app.inject()` 测试       |
+
+完整细节：[`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
+
+---
+
+## 已发布的包
+
+### [`xterm-zerolag-input`](https://www.npmjs.com/package/xterm-zerolag-input)
+
+[![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
+
+为 xterm.js 提供即时按键反馈的叠加层。通过把输入的字符立即渲染为像素级精准的 DOM 叠加层，消除高 RTT 连接下的感知输入延迟。零依赖、可配置的提示符检测、带 78 个测试的完整状态机。
+
+```bash
+npm install xterm-zerolag-input
+```
+
+[完整文档](packages/xterm-zerolag-input/README.md)
+
+---
+
+## 版本策略
+
+Codeman 遵循 [SemVer](https://semver.org/)。版本号真正承诺的内容，以及哪些算内部实现（HTTP/SSE API、磁盘上的状态、实验性特性），都写在 [`docs/versioning-policy.md`](docs/versioning-policy.md) 中。如果你的脚本依赖 HTTP API，请锁定到确切版本。
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  <strong>跟踪会话。可视化智能体。掌控重生。让它在你睡觉时持续运行。</strong>
+</p>

config/eslint.config.js

@@ -0,0 +1,28 @@
+// @ts-check
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    rules: {
+      'no-console': 'off',
+      'no-debugger': 'error',
+      // Relax some rules that conflict with existing patterns
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': 'off', // TypeScript compiler already handles this
+    },
+  },
+  {
+    ignores: [
+      'dist/**',
+      'node_modules/**',
+      'coverage/**',
+      'src/web/public/vendor/**',
+      'src/web/public/app.js',
+      'scripts/**/*.mjs',
+      'scripts/remotion/**',
+    ],
+  }
+);

config/knip.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "scripts/*.mjs",
+    "scripts/*.js",
+    "scripts/watch-subagents.ts",
+    "scripts/remotion/Root.tsx",
+    "scripts/remotion/index.ts",
+    "test/**/*.test.ts",
+    "test/mobile/vitest.config.ts",
+    "test/**/*.mjs"
+  ],
+  "project": ["src/**/*.{ts,tsx}", "scripts/**/*.{ts,tsx,mjs,js}", "test/**/*.{ts,mjs}"],
+  "ignoreExportsUsedInFile": true,
+  "ignoreDependencies": ["@remotion/cli", "@remotion/transitions", "esbuild", "agent-browser"]
+}

config/vitest.ci.config.ts

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { defineConfig, configDefaults } from 'vitest/config';
+
+const root = resolve(import.meta.dirname, '..');
+
+/**
+ * CI test config — same as vitest.config.ts but EXCLUDES the browser-driven
+ * mobile suite (test/mobile/**). Those are Playwright visual-regression tests
+ * that need a live server + chromium + environment-specific PNG baselines, so
+ * they are run/maintained separately and are not part of the CI gate.
+ *
+ * Keep the rest in sync with config/vitest.config.ts.
+ */
+export default defineConfig({
+  test: {
+    root,
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    exclude: [
+      ...configDefaults.exclude,
+      'test/mobile/**', // browser/visual (Playwright + chromium)
+      'test/perf-*.test.ts', // timing-sensitive perf benchmarks (flaky in CI)
+      'test/inline-rename.test.ts', // browser (Playwright)
+      'test/opencode-resize.test.ts', // browser (Playwright)
+      'test/webgl-fallback.test.ts', // browser (Playwright)
+    ],
+    setupFiles: ['./test/setup.ts'],
+    fileParallelism: false,
+    testTimeout: 30000,
+    teardownTimeout: 60000,
+  },
+});

config/vitest.config.ts

@@ -1,7 +1,11 @@
+import { resolve } from 'node:path';
 import { defineConfig } from 'vitest/config';
 
+const root = resolve(import.meta.dirname, '..');
+
 export default defineConfig({
   test: {
+    root,
     globals: true,
     environment: 'node',
     include: ['test/**/*.test.ts'],

docker/agent.Dockerfile

@@ -0,0 +1,65 @@
+# Codeman agent base image (built locally by scripts/build-agent-image.mjs).
+#
+# Contains the agent toolchain (node + the CLIs + git/tmux/ripgrep) but NO
+# secrets: credentials are delivered at RUNTIME via bind mounts (~/.claude etc.)
+# or name-only `docker exec --env`, never baked in, so `docker save` exports stay
+# secret-free. tmux is a HARD prerequisite (the in-container tmux is what makes a
+# reconnect durable), so it is installed here and probed before launch.
+#
+# HOME is made writable by an ARBITRARY host uid via the OpenShift "gid 0,
+# group-writable" convention: on Linux we run `--user <hostUid>:0`, so the agent
+# uid is the host uid (workspace files stay host-owned) while gid 0 keeps $HOME
+# writable even though the uid is not the baked 1000.
+FROM node:22-bookworm-slim
+
+# Base toolchain. `curl` is needed for the hook callbacks (`curl -sk $CODEMAN_API_URL`),
+# `procps` for `ps`, `tmux` for the durable in-container session.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      git \
+      tmux \
+      ripgrep \
+      curl \
+      ca-certificates \
+      less \
+      procps \
+      openssh-client \
+ && rm -rf /var/lib/apt/lists/*
+
+# The agent CLIs (all four backends Codeman supports). Pinning is left to the
+# rebuild cadence (see docs/docker-cases-plan.md, user-decision 2).
+RUN npm install -g \
+      @anthropic-ai/claude-code \
+      @openai/codex \
+      @google/gemini-cli \
+      opencode-ai \
+ && npm cache clean --force
+
+# `agent` user (gid 0) with an arbitrary-uid-writable HOME. The uid is
+# auto-assigned (node:22-slim already occupies uid 1000 with its `node` user); at
+# runtime Codeman overrides with `--user <hostUid>:0` on Linux, so the baked uid
+# only matters for a hand-run / Docker Desktop container. gid 0 + group-writable
+# HOME (OpenShift arbitrary-uid convention) keeps $HOME writable for any uid.
+# UTF-8 locale so tmux/Ink render Unicode box-drawing instead of VT100 ACS `q`
+# glyphs (C.UTF-8 is built into glibc; no locales package needed). Codeman also
+# sets these at run time so containers built before this line still get UTF-8.
+ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
+ENV HOME=/home/agent
+# `.claude` (+ `.claude/projects` mount point) and `.codex` (+ `.codex/sessions`) are
+# pre-created gid-0 group-writable so the container owns its OWN credential config
+# dirs: tokens/settings/config are seeded in as writable copies and each CLI's runtime
+# state (backups, tasks, refreshed tokens) stays container-local, while ONLY the shared
+# transcript/rollout dirs (`.claude/projects`, `.codex/sessions`) are bind-mounted from
+# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir.)
+RUN useradd -g 0 -m -d /home/agent -s /bin/bash agent \
+ && mkdir -p /home/agent/.npm /home/agent/.cache /home/agent/.config /home/agent/.codeman \
+      /home/agent/.claude/projects /home/agent/.codex/sessions \
+ && chgrp -R 0 /home/agent \
+ && chmod -R g=u /home/agent
+
+USER agent
+WORKDIR /home/agent
+
+# Codeman overrides the command with `sleep infinity` at create time; this is the
+# fallback so a hand-run container also idles rather than exiting.
+CMD ["sleep", "infinity"]

docs/SPEEDRUN.md

@@ -0,0 +1,104 @@
+# SPEEDRUN.md — Fast-execution protocol for Claude
+
+Read this when the goal is **throughput**: get correct, verified work done with
+minimum ceremony. This does **not** relax correctness or the safety rules in
+`CLAUDE.md` — those still win. It removes _waste_, not _rigor_.
+
+> Precedence: `CLAUDE.md` > explicit user instructions > this file. If anything
+> here conflicts with `CLAUDE.md`, `CLAUDE.md` wins.
+
+---
+
+## The mindset
+
+- **Act, don't announce.** No "I'm going to now…" preamble. Do the thing, report
+  the result.
+- **Cheapest proof that the change works.** Pick the smallest check that actually
+  demonstrates correctness — not the biggest.
+- **Batch aggressively.** Independent reads, greps, and edits go in **one**
+  message with parallel tool calls. Never serialize work that has no dependency.
+- **Momentum over perfection.** Land a correct increment, verify it, move on.
+  Don't gold-plate untouched code.
+
+---
+
+## Loop (repeat until done)
+
+1. **Orient once** — one parallel burst of reads/greps to load the context you
+   need. Don't re-read files the harness says are already current.
+2. **Change** — make the edit(s). Batch independent edits.
+3. **Verify cheaply** — the smallest check that proves _this_ change (see below).
+4. **Advance** — next item. Only re-verify what you touched.
+5. **Stop** at: list empty, a hard blocker, or a decision that's genuinely the
+   user's to make.
+
+---
+
+## Verification ladder — climb only as high as the change needs
+
+| Change kind | Cheapest sufficient check |
+|-------------|---------------------------|
+| Types / signatures / imports | `tsc --noEmit` (or `--watch` already running) |
+| One module's logic | `npm test -- test/<file>.test.ts` (the **one** relevant file) |
+| A named behavior | `npm test -- -t "pattern"` |
+| Route/handler | `app.inject()` route test, or one `curl` against the running dev server |
+| Frontend render | Playwright load + assert (`waitUntil: 'domcontentloaded'`, wait 3–4s) |
+| Broad / pre-merge | `npm run test:ci` (the CI-equivalent sweep) |
+
+**Hard rules (never skip, even in a rush):**
+- ⚠️ **Never run bare `npm test`** — it pulls in browser/visual suites that hang
+  or fail locally. Always pass a file or `-t`, or use `test:ci`.
+- ⚠️ **Never COM without verifying the change actually works** first (curl the
+  endpoint / Playwright the UI). "Compiles" ≠ "works".
+- ⚠️ **Session safety** — check `$CODEMAN_MUX`; never `tmux kill-session` /
+  `pkill claude` in a managed session.
+- ⚠️ **Single-line prompts** for any programmatic session input.
+
+---
+
+## Speed tactics that pay off here
+
+- **Parallel exploration**: dispatch `Explore` subagents (or one parallel grep
+  burst) instead of serial file-by-file reading when scope is uncertain.
+- **`tsc --noEmit --watch`** in the background — instant type feedback, no repeat
+  cold starts.
+- **Target one test file** — `fileParallelism: false` means the suite is serial;
+  running one file is dramatically faster than the sweep.
+- **`curl localhost:3000/api/...`** beats spinning up a browser for backend
+  checks. Reserve Playwright for actual UI rendering.
+- **Trust the harness** — if it says a file you just edited is current, don't
+  re-Read it to "confirm". The Edit already succeeded or it would have errored.
+
+---
+
+## Anti-patterns (these masquerade as speed, but cost time)
+
+- Running the full test suite to check a one-file change.
+- Re-reading files you already have in context.
+- Narrating a plan you're about to execute anyway.
+- Serial tool calls that have no dependency between them.
+- Claiming "done / fixed / passing" **before** running the check that proves it.
+- Deploying (COM) on green typecheck alone, without exercising the real flow.
+
+---
+
+## Stop-conditions (don't rush past these)
+
+Stop and surface, don't guess, when you hit:
+- A **destructive / hard-to-reverse** action (delete, overwrite, force-push).
+- An **outward-facing** action (publishing, sending, deploying) not already
+  authorized.
+- A **genuine product decision** the code can't answer.
+- A **failing verification you can't explain** — debug it (see
+  `superpowers:systematic-debugging`), don't paper over it.
+
+---
+
+## Definition of done
+
+A task is done when **all** hold:
+- The change is made.
+- The cheapest sufficient check **ran** and **passed** — evidence, not assertion.
+- No new type errors / lint errors introduced (`tsc --noEmit`, `npm run lint`).
+- You state plainly what was done and what proved it. If a step was skipped or a
+  test failed, say so — don't hedge, don't overclaim.

docs/api-reference.md

@@ -0,0 +1,90 @@
+# HTTP API Reference
+
+Codeman's HTTP API is a **stable contract** as of 1.0 — see
+[`versioning-policy.md`](versioning-policy.md) for the SemVer guarantee. This page
+defines the response envelope, status codes, error codes, versioning, and the SSE
+event channel.
+
+## Versioning
+
+- The stable, public surface is served under **`/api/v1/...`**. Pin external
+  clients to this prefix.
+- The unversioned **`/api/...`** paths are a permanent alias of the current
+  version (what the bundled web UI uses). They are kept working, but new external
+  integrations should use `/api/v1`.
+- Breaking changes to the contract ship under a new prefix (`/api/v2`); `/api/v1`
+  keeps its semantics. Additive changes (new endpoints, new optional fields, new
+  error codes) are non-breaking and may appear in a minor release.
+- The implementation rewrites `/api/v1/*` → `/api/*` at the server level
+  (`rewriteApiV1Url` in `src/web/server.ts`).
+
+## Response envelope
+
+Every JSON response uses one uniform envelope, applied centrally by a
+`preSerialization` hook (`src/web/server.ts`) — handlers return bare data and the
+hook wraps it:
+
+**Success** — HTTP `2xx`:
+
+```json
+{ "success": true, "data": <payload> }
+```
+
+`data` is the endpoint's payload (object, array, or value). Endpoints with no
+payload return `{ "success": true, "data": {} }`.
+
+**Error** — HTTP `4xx`/`5xx`:
+
+```json
+{ "success": false, "error": "human-readable message", "errorCode": "NOT_FOUND" }
+```
+
+`ApiResponse<T>` in `src/types/api.ts` is the canonical type.
+
+> Non-JSON endpoints are exempt from the envelope: `GET /api/sessions/:id/file-raw`,
+> `GET /api/sessions/:id/tail-file` (SSE), `GET /api/download`,
+> `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect), and the
+> `GET /ws/sessions/:id/terminal` WebSocket upgrade.
+
+## Error codes → HTTP status
+
+The single source of truth is `ErrorStatus` / `httpStatusForErrorCode()` in
+`src/types/api.ts`. Clients should branch on `errorCode` (stable) and may rely on
+the HTTP status.
+
+| `errorCode` | HTTP | Meaning |
+|-------------|------|---------|
+| `INVALID_INPUT` | 400 | Malformed request / failed validation |
+| `UNAUTHORIZED` | 401 | Authentication required or failed |
+| `NOT_FOUND` | 404 | Resource does not exist |
+| `SESSION_BUSY` | 409 | Session is busy |
+| `CONFLICT` | 409 | Conflicts with current state (e.g. already running) |
+| `ALREADY_EXISTS` | 409 | Resource already exists |
+| `OPERATION_FAILED` | 422 | Well-formed but could not be completed |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Unexpected server error |
+
+Adding a new error code is non-breaking; removing or renaming one is a major change.
+
+## Authentication
+
+Optional HTTP Basic (`CODEMAN_USERNAME`/`CODEMAN_PASSWORD`) → opaque
+`codeman_session` cookie. When enabled, unauthenticated requests get
+`401 UNAUTHORIZED`; rate-limited requests get `429 RATE_LIMITED`. See
+[`security-architecture.md`](security-architecture.md).
+
+## SSE event channel
+
+`GET /api/events` is a Server-Sent Events stream (`text/event-stream`); each
+message is `event: <name>` + `data: <json>`. The event-name registry
+(`src/web/sse-events.ts`, mirrored in `src/web/public/constants.js`) is part of
+the stable contract — event names are not renamed without a major bump. An
+optional `?sessions=<id,...>` filter suppresses only the high-volume terminal
+stream; lifecycle/metadata events are delivered to all clients regardless.
+
+## Consuming from JavaScript
+
+The bundled frontend reads responses through `_apiJson()`
+(`src/web/public/api-client.js`), which unwraps `{success:true,data}` → `data` and
+returns `null` on a non-2xx / `{success:false}` response. External clients should
+do the same: check the HTTP status (or `body.success`), then read `body.data`.

docs/archive/cleanup-findings.md

@@ -1,3 +1,9 @@
+> **⚠️ ARCHIVED 2026-05-21 — superseded, kept for history.**
+> The headline items here were verified resolved: the P0 `{WORKING_DIR}` placeholder
+> is now replaced (`plan-orchestrator.ts:431`), and the "~66 dead functions in app.js"
+> are gone (app.js was modularized 15K→3K LOC). A fresh `npm run knip` sweep on
+> 2026-05-21 found only a handful of unused test helpers. Do not treat this as a live TODO.
+
 # Codebase Cleanup Findings
 
 Compiled from parallel analysis of the entire Codeman codebase by 3 research agents (2026-02-19).

docs/archive/code-structure-findings.md

@@ -0,0 +1,983 @@
+> **⚠️ ARCHIVED 2026-05-21 — superseded, kept for history.**
+> The "Critical" structural items here are done: `server.ts` 6,736→2,065 LOC,
+> `app.js` 15,196→3,083 LOC, `types.ts` 1,443→12 LOC (now a barrel → `src/types/`).
+> The phase plans that executed this work are in `docs/archive/phase*-plan.md`.
+> Do not treat this as a live TODO; see CLAUDE.md for current architecture.
+
+# Code Structure & Quality Findings
+
+**Date**: 2026-02-28
+**Scope**: Full codebase analysis across 5 dimensions: frontend, backend, TypeScript, testing, and utilities/config.
+
+This document contains detailed findings for agent teams to write implementation plans and execute improvements. Each section includes severity, specific locations, and recommended fixes.
+
+---
+
+## Table of Contents
+
+1. [Critical: server.ts God Object (6,736 LOC)](#1-critical-serverts-god-object)
+2. [Critical: app.js Monolith (15,196 LOC)](#2-critical-appjs-monolith)
+3. [Critical: CleanupManager Unused Despite Existing](#3-critical-cleanupmanager-unused)
+4. [High: Duplicated Debounce/Timer Patterns](#4-high-duplicated-debouncetimer-patterns)
+5. [High: Large Domain Files Need Splitting](#5-high-large-domain-files-need-splitting)
+6. [High: types.ts God File (1,443 LOC)](#6-high-typests-god-file)
+7. [High: Zod Schemas Duplicate TypeScript Types](#7-high-zod-schemas-duplicate-typescript-types)
+8. [High: Test Coverage Gaps](#8-high-test-coverage-gaps)
+9. [High: Duplicated Test Mocks](#9-high-duplicated-test-mocks)
+10. [Medium: Hardcoded Magic Values](#10-medium-hardcoded-magic-values)
+11. [Medium: Frontend Global State Monolith](#11-medium-frontend-global-state-monolith)
+12. [Medium: Frontend Code Duplication](#12-medium-frontend-code-duplication)
+13. [Medium: Inconsistent Logging](#13-medium-inconsistent-logging)
+14. [Medium: Utils Barrel Export Gaps](#14-medium-utils-barrel-export-gaps)
+15. [Medium: Non-Null Assertion Risks](#15-medium-non-null-assertion-risks)
+16. [Low: Dead Utility Functions](#16-low-dead-utility-functions)
+17. [Low: No Dependency Injection for File I/O](#17-low-no-dependency-injection-for-file-io)
+18. [Scorecard & Prioritized Roadmap](#18-scorecard--prioritized-roadmap)
+
+---
+
+## 1. Critical: server.ts God Object
+
+**File**: `src/web/server.ts` (6,736 lines)
+**Severity**: CRITICAL
+**Impact**: Hardest file to maintain, test, and extend. Imports 38 modules.
+
+### Problem
+
+The `WebServer` class handles everything: HTTP routing (~110 routes), authentication, SSE broadcasting, terminal data batching, state persistence, session lifecycle, respawn orchestration, file serving, tunnel management, plan orchestration, and subagent coordination.
+
+**Key metrics**:
+- 40+ private properties (Maps, timers, caches)
+- 70+ methods
+- `setupRoutes()` is 2,000+ LOC of inline route handlers
+- Zero test coverage
+
+### Current Structure (Bad)
+
+```
+WebServer class (6,736 LOC)
+├── Auth session management (lines 469, 668-698)
+├── SSE client management (lines 407-408, 5843-5880)
+├── Terminal data batching (lines 414-416, 5909-5966)
+├── Task update batching (line 426, 5995-6028)
+├── State persistence batching (lines 429-430, 6028-6061)
+├── Respawn lifecycle (lines 445-451, 5425-5534)
+├── Session cleanup (lines 4769-4961)
+├── Listener setup (lines 544-643)
+└── setupRoutes() (lines 645+, 2000+ LOC)
+    ├── /api/sessions/* (30+ routes inline)
+    ├── /api/respawn/* (7 routes inline)
+    ├── /api/subagents/* (7 routes inline)
+    ├── /api/plan/* (5 routes inline)
+    ├── /api/push/* (4 routes inline)
+    └── ... 60+ more inline
+```
+
+### Recommended Structure
+
+```
+src/web/
+├── server.ts              (~500 LOC - HTTP setup, route registration only)
+├── routes/
+│   ├── session-routes.ts  (session CRUD, input, resize)
+│   ├── respawn-routes.ts  (respawn control endpoints)
+│   ├── subagent-routes.ts (background agent tracking)
+│   ├── plan-routes.ts     (plan generation & management)
+│   ├── push-routes.ts     (web push subscriptions)
+│   ├── mux-routes.ts      (tmux management)
+│   ├── case-routes.ts     (case management)
+│   ├── file-routes.ts     (file browsing/serving)
+│   └── system-routes.ts   (status, stats, config, settings)
+├── middleware/
+│   ├── auth.ts            (Basic Auth + session cookies)
+│   └── error-handler.ts   (centralized error responses)
+└── services/
+    ├── sse-manager.ts     (SSE client + broadcast)
+    ├── terminal-batcher.ts (60fps terminal batching)
+    └── session-lifecycle.ts (listener setup/teardown)
+```
+
+### Duplication in server.ts
+
+**Error response pattern** repeated 189 times:
+```typescript
+return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
+```
+
+**Fix**: Extract `findSessionOrFail()` middleware:
+```typescript
+const findSessionOrFail = (sessionId: string) => {
+  const session = this.sessions.get(sessionId);
+  if (!session) throw new NotFoundError('Session not found');
+  return session;
+};
+```
+
+**Event listener setup** copy-pasted for subagent watcher, image watcher, and team watcher (lines 544-643). Same attach/detach pattern duplicated 3 times.
+
+---
+
+## 2. Critical: app.js Monolith
+
+**File**: `src/web/public/app.js` (15,196 lines)
+**Severity**: CRITICAL
+**Impact**: Untestable, hard to navigate, tightly coupled systems.
+
+### Extractable Modules (by priority)
+
+| Module | Lines | Current Location | Impact |
+|--------|-------|------------------|--------|
+| Mobile handlers (MobileDetection, KeyboardHandler, SwipeHandler) | ~300 | lines 168-620 | High |
+| Voice input (DeepgramProvider, VoiceInput) | ~830 | lines 631-1471 | High |
+| NotificationManager | ~450 | lines 2218-2663 | High |
+| xterm-zerolag-input (inlined copy from packages/) | ~400 | lines 1756-2153 | High |
+| KeyboardAccessoryBar | ~195 | lines 1480-1680 | Medium |
+| FocusTrap | ~60 | lines 1690-1748 | Medium |
+
+### CodemanApp Class (12,000+ LOC)
+
+The main `CodemanApp` class starting at line 2665 has:
+- **60+ Maps/Sets** in the constructor (lines 2667-2805)
+- **18 Map instances** with complex cross-references (subagents, parents, teams, windows)
+- **10+ monolithic methods** exceeding 100 lines each
+
+**Largest methods**:
+| Method | Lines | Size |
+|--------|-------|------|
+| `renderAppSettings()` | 14400-14700 | ~300 LOC |
+| `selectSession()` | 6028-6250 | ~220 LOC |
+| `batchTerminalWrite()` | 7482-7700 | ~200 LOC |
+| `renderSessionTabs()` | 5814-6000 | ~180 LOC |
+| `openSubagentWindow()` | 11927-12100 | ~170 LOC |
+| `handleInit()` | 5183-5350 | ~170 LOC |
+
+### Recommended Split
+
+```
+src/web/public/
+├── app.js                 (~4000 LOC - core app, session mgmt, SSE)
+├── mobile.js              (~300 LOC - MobileDetection, KeyboardHandler, SwipeHandler)
+├── voice.js               (~830 LOC - DeepgramProvider, VoiceInput)
+├── notifications.js       (~450 LOC - NotificationManager)
+├── keyboard-accessory.js  (~200 LOC - KeyboardAccessoryBar)
+├── api-client.js          (~100 LOC - fetch wrapper with error handling)
+└── config.js              (~50 LOC - magic numbers, z-index layers)
+```
+
+---
+
+## 3. Critical: CleanupManager Unused
+
+**File**: `src/utils/cleanup-manager.ts` (320 lines)
+**Severity**: CRITICAL
+**Impact**: Memory leak risk. Well-designed utility exists but is never used. Every file manages cleanup manually.
+
+### Current State
+
+`CleanupManager` is exported from the utils barrel but has **0 instantiations** in production code. Instead, every file implements manual cleanup:
+
+**respawn-controller.ts** (worst offender):
+```typescript
+// 11 timer properties, manually cleared in stop()
+private stepTimer: NodeJS.Timeout | null = null;
+private completionConfirmTimer: NodeJS.Timeout | null = null;
+private noOutputTimer: NodeJS.Timeout | null = null;
+// ... 8 more
+
+stop() {
+  if (this.stepTimer) clearTimeout(this.stepTimer);
+  if (this.completionConfirmTimer) clearTimeout(this.completionConfirmTimer);
+  // ... 9 more clearTimeout/clearInterval calls
+}
+```
+
+**Files that should use CleanupManager**:
+| File | Timer/Listener Count | Current Cleanup |
+|------|---------------------|-----------------|
+| `respawn-controller.ts` | 11 timers + intervals | 11 manual clearTimeout/clearInterval |
+| `web/server.ts` | 6+ timers, debounce map | Manual in stop(), some may leak |
+| `state-store.ts` | 2 debounce timers | Manual clearTimeout |
+| `push-store.ts` | 1 save timer | Manual clearTimeout |
+| `subagent-watcher.ts` | debounce map + watchers | Manual clear + close |
+| `ralph-tracker.ts` | 3 debounce timers | Manual clear |
+| `bash-tool-parser.ts` | 1 debounce timer | Manual clear |
+| `image-watcher.ts` | 1 debounce map | Manual clear |
+
+### Fix
+
+Migrate all timer management to use `CleanupManager`. Example for respawn-controller.ts:
+
+```typescript
+// Before: 11 fields + 11 clearTimeout calls
+private stepTimer: NodeJS.Timeout | null = null;
+// ...
+
+// After: 1 field, auto-cleanup
+private cleanup = new CleanupManager();
+
+startStep() {
+  this.cleanup.setTimeout(() => { ... }, 5000, 'step');
+}
+
+stop() {
+  this.cleanup.dispose(); // Clears everything
+}
+```
+
+---
+
+## 4. High: Duplicated Debounce/Timer Patterns
+
+**Severity**: HIGH
+**Impact**: 8+ files implement debounce independently. Bug fixes need to be applied everywhere.
+
+### Pattern Inventory
+
+```typescript
+// Pattern 1: Manual timer ref (used in 6 files)
+private saveTimer: NodeJS.Timeout | null = null;
+debouncedSave() {
+  if (this.saveTimer) clearTimeout(this.saveTimer);
+  this.saveTimer = setTimeout(() => this.save(), 500);
+}
+
+// Pattern 2: Timer Map (used in 3 files)
+private fileDebouncers = new Map<string, NodeJS.Timeout>();
+debounce(key: string) {
+  const existing = this.fileDebouncers.get(key);
+  if (existing) clearTimeout(existing);
+  this.fileDebouncers.set(key, setTimeout(() => { ... }, 100));
+}
+
+// Pattern 3: State flag (used in 2 files)
+private isSaving = false;
+```
+
+### Locations
+
+| File | Debounce Vars | Delay (ms) |
+|------|---------------|------------|
+| `state-store.ts` | `saveTimeout`, `ralphStateSaveTimeout` | 500 |
+| `push-store.ts` | `saveTimer` | 500 |
+| `web/server.ts` | `persistDebounceTimers` (Map) | 500 |
+| `subagent-watcher.ts` | `fileDebouncers` (Map) | 100 |
+| `ralph-tracker.ts` | 3 debounce timers | 50, 30000 |
+| `bash-tool-parser.ts` | `EVENT_DEBOUNCE_MS` | 50 |
+| `image-watcher.ts` | debounce map | 200 |
+| `respawn-controller.ts` | 11 timer fields | various |
+
+### Fix
+
+Create a `Debouncer` utility:
+
+```typescript
+// src/utils/debouncer.ts
+export class Debouncer {
+  private timer: NodeJS.Timeout | null = null;
+
+  constructor(private readonly delayMs: number) {}
+
+  run(fn: () => void): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(fn, this.delayMs);
+  }
+
+  cancel(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+}
+
+// Usage:
+private saveDeb = new Debouncer(500);
+this.saveDeb.run(() => this.save());
+// cleanup: this.saveDeb.cancel();
+```
+
+---
+
+## 5. High: Large Domain Files Need Splitting
+
+**Severity**: HIGH
+**Impact**: Complex state machines spanning 3,000+ lines are hard to understand and test.
+
+### ralph-tracker.ts (3,905 LOC)
+
+**5 responsibilities mixed**:
+1. Output Parsing (~900 LOC) - Line-by-line parsing, state extraction
+2. Todo Management (~700 LOC) - Parsing, dedup, expiry
+3. Plan Tracking (~800 LOC) - Enhanced plan tasks, checkpoints
+4. Circuit Breaker (~400 LOC) - State machine for stuck detection
+5. File Watching (~300 LOC) - Monitor external state files
+
+**Recommended split**:
+```
+ralph-tracker.ts          (core output parsing, ~1200 LOC)
+ralph-todo-manager.ts     (todo parsing + management, ~700 LOC)
+ralph-plan-tracker.ts     (plan tasks + checkpoints, ~800 LOC)
+ralph-circuit-breaker.ts  (circuit breaker logic, ~400 LOC)
+```
+
+### respawn-controller.ts (3,611 LOC)
+
+**6 responsibilities mixed**:
+1. State Machine (~1,000 LOC) - 6+ states, transitions
+2. Idle Detection (~800 LOC) - 5 layers + multi-signal combining
+3. AI Checkers (~600 LOC) - Idle + plan checkers integration
+4. Health Scoring (~500 LOC) - Metrics, circuit breaker, scoring
+5. Action Logging (~300 LOC) - Timeline, detection status
+6. Stuck-State Detection (~250 LOC) - Timeout tracking
+
+**Recommended split**:
+```
+respawn-controller.ts         (state machine core, ~1000 LOC)
+respawn-idle-detection.ts     (all 5 idle detection layers, ~800 LOC)
+respawn-health-scorer.ts      (metrics & health scoring, ~500 LOC)
+```
+
+### session.ts (2,418 LOC)
+
+**8 responsibilities mixed**:
+1. PTY Management (~600 LOC)
+2. Terminal I/O (~400 LOC)
+3. Token Tracking (~200 LOC)
+4. Task Tracking (~250 LOC)
+5. Ralph Integration (~200 LOC)
+6. Auto-Clear/Compact (~300 LOC)
+7. Image Watching (~100 LOC)
+8. CLI Detection (~150 LOC)
+
+**Recommended split**:
+```
+session.ts               (PTY + terminal I/O core, ~1000 LOC)
+session-tracking.ts      (token + task + Ralph, ~500 LOC)
+session-auto-ops.ts      (auto-clear/compact + image, ~300 LOC)
+```
+
+---
+
+## 6. High: types.ts God File
+
+**File**: `src/types.ts` (1,443 lines, 72 exported definitions)
+**Severity**: HIGH
+**Impact**: Every file imports from types.ts. Hard to find relevant types.
+
+### Current Contents
+
+- 46 interfaces
+- 25 types
+- 1 enum (ApiErrorCode)
+- 9 factory functions (createInitialState, etc.)
+
+### Recommended Split
+
+```
+src/types/
+├── index.ts          (barrel export - transparent migration)
+├── session.ts        (SessionState, SessionConfig, SessionMode, SessionColor)
+├── task.ts           (TaskState, TaskDefinition, TaskStatus)
+├── respawn.ts        (RespawnConfig, RespawnState, CircuitBreakerStatus)
+├── ralph.ts          (RalphLoopState, RalphTrackerState, RalphTodoItem)
+├── api.ts            (ApiResponse, ApiErrorCode, HookEventType, all route types)
+├── lifecycle.ts      (LifecycleEventType, LifecycleEntry)
+└── common.ts         (Disposable, BufferConfig, CleanupResourceType)
+```
+
+The barrel export makes this a transparent refactor - existing `import from './types'` continues to work.
+
+---
+
+## 7. High: Zod Schemas Duplicate TypeScript Types
+
+**File**: `src/web/schemas.ts` (508 lines)
+**Severity**: HIGH
+**Impact**: When a type changes, the Zod schema must be manually updated too. Source of bugs.
+
+### Problem
+
+Zod schemas manually duplicate TypeScript interfaces. **Zero `z.infer` usage found.**
+
+```typescript
+// types.ts (manual interface)
+export interface CreateSessionRequest {
+  workingDir?: string;
+  mode?: SessionMode;
+  name?: string;
+}
+
+// schemas.ts (manual Zod schema - duplicated!)
+export const CreateSessionSchema = z.object({
+  workingDir: safePathSchema.optional(),
+  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
+  name: z.string().max(100).optional(),
+});
+```
+
+### Fix
+
+Use `z.infer` to derive TypeScript types from Zod schemas (single source of truth):
+
+```typescript
+// schemas.ts
+export const CreateSessionSchema = z.object({
+  workingDir: safePathSchema.optional(),
+  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
+  name: z.string().max(100).optional(),
+});
+
+// types.ts (auto-derived)
+export type CreateSessionRequest = z.infer<typeof CreateSessionSchema>;
+```
+
+**Affected schemas** (~10):
+- CreateSessionSchema
+- RunPromptSchema
+- ResizeSchema
+- CreateCaseSchema
+- QuickStartSchema
+- HookEventSchema
+- RespawnConfigSchema
+- ConfigUpdateSchema
+- SettingsUpdateSchema
+
+---
+
+## 8. High: Test Coverage Gaps
+
+**Severity**: HIGH
+**Impact**: Critical code paths untested. Regressions go unnoticed.
+
+### Untested Source Files
+
+| File | Lines | Risk |
+|------|-------|------|
+| `src/web/server.ts` | 6,736 | CRITICAL - Core REST API, 280+ routes |
+| `src/plan-orchestrator.ts` | ~500 | HIGH - Multi-agent plan generation |
+| `src/tunnel-manager.ts` | ~200 | MEDIUM - Cloudflare tunnel |
+| `src/session-lifecycle-log.ts` | ~150 | MEDIUM - JSONL audit log |
+| `src/ai-plan-checker.ts` | ~300 | MEDIUM - Plan completion detection |
+| `src/templates/claude-md.ts` | ~200 | LOW - CLAUDE.md generation |
+| `src/utils/claude-cli-resolver.ts` | ~100 | LOW - CLI path resolution |
+| `src/utils/opencode-cli-resolver.ts` | ~100 | LOW - OpenCode CLI support |
+| `src/utils/regex-patterns.ts` | ~100 | LOW - Used everywhere! |
+| `src/utils/token-validation.ts` | ~50 | LOW - Token counting |
+
+### Test Quality Issues
+
+**10 "not.toThrow()" tests without behavior verification**:
+```typescript
+// BAD: Only checks it doesn't crash
+expect(() => tracker.processMessage(null)).not.toThrow();
+
+// GOOD: Also verify defensive behavior
+expect(() => tracker.processMessage(null)).not.toThrow();
+expect(tracker.getAllTasks().size).toBe(0);
+```
+
+Locations:
+- `task-tracker.test.ts` - 5 instances
+- `image-watcher.test.ts` - 1 instance
+- `task-queue.test.ts` - 1 instance
+- Others scattered
+
+---
+
+## 9. High: Duplicated Test Mocks
+
+**Severity**: HIGH
+**Impact**: Mock changes need updating in 4 places. Inconsistent mock behavior.
+
+### MockSession Defined 4 Times
+
+| File | Usage |
+|------|-------|
+| `test/respawn-controller.test.ts` | Full mock with event emitter |
+| `test/session-manager.test.ts` | Simpler mock |
+| `test/respawn-team-awareness.test.ts` | Copy of respawn-controller mock |
+| `test/respawn-test-utils.ts` | **Comprehensive mock - UNUSED!** |
+
+### MockStateStore Defined 2 Times
+
+| File | Usage |
+|------|-------|
+| `test/session-manager.test.ts` | Basic mock |
+| `test/ralph-loop.test.ts` | Separate implementation |
+
+### Unused Test Utilities
+
+`test/respawn-test-utils.ts` exports these utilities that **no test file imports**:
+- `createTimeController()` - Abstraction over vitest fake timers
+- `MockAiIdleChecker` - Fully mocked AI idle checker
+- `MockAiPlanChecker` - Fully mocked plan checker
+- Factory functions for pre-configured controllers
+
+### Fix
+
+Create `test/mocks/` directory:
+```
+test/
+├── mocks/
+│   ├── mock-session.ts      (single MockSession, used everywhere)
+│   ├── mock-state-store.ts  (single MockStateStore)
+│   └── index.ts             (barrel export)
+├── utils/
+│   └── time-controller.ts   (from respawn-test-utils.ts)
+└── ... test files
+```
+
+---
+
+## 10. Medium: Hardcoded Magic Values
+
+**Severity**: MEDIUM
+**Impact**: Hard to tune, inconsistent when same value appears in multiple places.
+
+### Already Centralized (Good)
+
+- `src/config/buffer-limits.ts` - All buffer sizes
+- `src/config/map-limits.ts` - All collection limits
+
+### NOT Centralized (40+ values scattered)
+
+**In server.ts** (lines 145-194):
+```typescript
+const TASK_UPDATE_BATCH_INTERVAL = 100;
+const STATE_UPDATE_DEBOUNCE_INTERVAL = 500;
+const SESSIONS_LIST_CACHE_TTL = 1000;
+const SCHEDULED_CLEANUP_INTERVAL = 5 * 60 * 1000;
+const SSE_HEALTH_CHECK_INTERVAL = 30 * 1000;
+const MAX_TERMINAL_COLS = 500;
+const MAX_TERMINAL_ROWS = 200;
+const AUTH_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_AUTH_SESSIONS = 100;
+const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
+const STATS_COLLECTION_INTERVAL_MS = 2000;
+const MAX_INPUT_LENGTH = 64 * 1024;
+```
+
+**In hooks-config.ts**: `timeout: 10000` hardcoded 6 times.
+
+**In respawn-controller.ts** (lines 538-565): 10 timing constants.
+
+**In utils**: `EXEC_TIMEOUT_MS = 5000` duplicated in both `claude-cli-resolver.ts` and `opencode-cli-resolver.ts`.
+
+**In app.js**:
+```javascript
+// line 27: 600000 - stuck detection threshold
+// line 24: 5000 - default scrollback
+// lines 34-35: 128*1024, 256*1024 - chunk sizes
+// lines 152-155: 150, 100 - keyboard detection thresholds
+// lines 573-575: 80, 300, 100 - swipe detection params
+```
+
+### Fix
+
+Create additional config files:
+```
+src/config/
+├── buffer-limits.ts     (existing)
+├── map-limits.ts        (existing)
+├── server-config.ts     (NEW - web server intervals, auth, caching)
+├── timing-config.ts     (NEW - debounce delays, check intervals)
+└── terminal-config.ts   (NEW - max cols/rows, batch intervals)
+```
+
+---
+
+## 11. Medium: Frontend Global State Monolith
+
+**Severity**: MEDIUM
+**Impact**: All state in single CodemanApp class. Tight coupling between unrelated systems.
+
+### 60+ State Variables in CodemanApp Constructor (lines 2667-2805)
+
+```javascript
+this.sessions = new Map();             // Session data
+this.subagents = new Map();            // Agent tracking
+this.subagentActivity = new Map();     // Tool call tracking
+this.subagentToolResults = new Map();  // Result caching
+this.subagentParentMap = new Map();    // Agent-to-session mapping
+this.teams = new Map();                // Team tracking
+this.teamTasks = new Map();           // Team task state
+this.planSubagents = new Map();        // Plan agent tracking
+this.pendingWrites = [];               // Terminal write queue
+this.terminalBufferCache = new Map();  // Buffer caching (unbounded!)
+this.projectInsights = new Map();      // Bash tool insights
+// ... 40+ more
+```
+
+### Problems
+
+1. **18 Map instances** with complex cross-references (no garbage collection strategy)
+2. **No domain separation**: Session, subagent, notification, UI, and network state mixed
+3. **Implicit dependencies**: `selectSession()` requires 5+ Maps to be in consistent state
+4. **`terminalBufferCache`** has no max size - can grow unbounded with many sessions
+
+### Recommended Domain Split
+
+```javascript
+// Instead of 60+ flat properties:
+class SessionState {
+  sessions = new Map();
+  sessionOrder = [];
+  terminalBuffers = new Map();
+  tabAlerts = new Map();
+}
+
+class SubagentState {
+  subagents = new Map();
+  activity = new Map();
+  parentMap = new Map();
+  windows = new Map();
+  minimized = new Map();
+}
+
+class TeamState {
+  teams = new Map();
+  tasks = new Map();
+  teammates = new Map();
+}
+
+class UIState {
+  activeSessionId = null;
+  draggedTabId = null;
+  isLoadingBuffer = false;
+}
+```
+
+---
+
+## 12. Medium: Frontend Code Duplication
+
+**Severity**: MEDIUM
+**Impact**: Repeated patterns increase maintenance burden and inconsistency risk.
+
+### Duplicated Patterns
+
+**API fetch calls** (~50 instances):
+```javascript
+// Repeated everywhere:
+fetch(`/api/sessions/${sessionId}/...`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({...})
+}).catch(() => {})
+```
+**Fix**: Extract `ApiClient` class.
+
+**`innerHTML` usage** (104 instances):
+- Mix of template strings, createElement chains, and direct innerHTML
+- Some with manual XSS escaping (`text.replace(/</g, '&lt;')`), some without
+- No consistent DOM creation pattern
+
+**`typeof app !== 'undefined'` checks** (20+ instances):
+- Lines 458, 467, 481, 614, 617, 1549, etc.
+- **Fix**: Ensure `app` is always defined as global singleton.
+
+**Element visibility toggling** (212+ occurrences):
+```javascript
+element.classList.add('active')
+element.classList.remove('active')
+```
+**Fix**: Create `toggleClass(el, className, condition)` utility.
+
+### Event Listener Issues
+
+- **152 `addEventListener` calls** with fragile cleanup
+- **Mix of inline (`onclick="app.method()"`) and addEventListener** - hard to track
+- **Element cache (`_elemCache`) never invalidated** if DOM elements are recreated (line 2808)
+- **Tab drag-and-drop listeners** may not clean up if user switches tabs mid-drag
+
+---
+
+## 13. Medium: Inconsistent Logging
+
+**Severity**: MEDIUM
+**Impact**: Hard to debug in production. Can't filter by severity or component.
+
+### Current State
+
+- **345 console calls** across source files
+- **No structured logging** - all `console.log/error` directly
+- **No log levels** (DEBUG, INFO, WARN, ERROR)
+
+### Inconsistent Prefixes
+
+```typescript
+// Some files use brackets:
+console.log('[Session] Starting interactive...');
+console.log('[RalphLoop] Task assigned...');
+console.log('[TunnelManager] Tunnel started');
+
+// Others use no prefix:
+console.error('Failed to spawn PTY:', err);
+console.log('Server listening on port', port);
+```
+
+### Positive: CleanupManager Has Debug Mode
+
+`src/utils/cleanup-manager.ts` has a `debugMode` flag for conditional debug logging - good pattern not replicated elsewhere.
+
+### Fix
+
+Either:
+1. Enforce consistent `[ComponentName]` prefixes via lint rule
+2. Create lightweight logger abstraction (not a heavy framework)
+
+---
+
+## 14. Medium: Utils Barrel Export Gaps
+
+**File**: `src/utils/index.ts`
+**Severity**: MEDIUM
+**Impact**: Forces deep imports, unclear public API.
+
+### Missing Exports
+
+These functions are defined but NOT exported from the barrel:
+- `createAnsiPatternFull()` and `createAnsiPatternSimple()` (factory functions from `regex-patterns.ts`)
+- `SAFE_PATH_PATTERN` (from `regex-patterns.ts`)
+- `validateTokenCounts()` and `validateTokensAndCost()` (from `token-validation.ts`)
+- `isSimilar()`, `isSimilarByDistance()`, `levenshteinDistance()`, `normalizePhrase()` (from `string-similarity.ts` - though some are dead code, see finding #16)
+
+### Deep Import Anti-Pattern (16 instances)
+
+Some files bypass the barrel unnecessarily:
+```typescript
+// Could use barrel:
+import { BufferAccumulator } from './utils/buffer-accumulator.js';
+import { LRUMap } from './utils/lru-map.js';
+
+// Must deep import (not in barrel):
+import { SAFE_PATH_PATTERN } from './utils/regex-patterns.js';
+```
+
+### Fix
+
+Add missing exports to `src/utils/index.ts` and update import sites.
+
+---
+
+## 15. Medium: Non-Null Assertion Risks
+
+**Severity**: MEDIUM
+**Impact**: Runtime crashes if assumptions violated. 37 instances found.
+
+### Distribution
+
+| File | Count | Risk Level |
+|------|-------|------------|
+| `src/web/server.ts` | 10 | Low (auth flow verified) |
+| `src/session.ts` | 6 | **High** (mux/terminal refs) |
+| `src/respawn-controller.ts` | 4 | Low (config validated) |
+| `src/lru-map.ts` | 3 | Low (checked lookups) |
+| `src/subagent-watcher.ts` | 2 | Low (pending tool calls) |
+| Others | 12 | Low |
+
+### High-Risk Examples (session.ts)
+
+```typescript
+// Line 915 - _mux could be null if startInteractive called during cleanup
+`[Session] Starting interactive (with ${this._mux!.backend})`
+
+// Line 954 - _muxSession could be null in race condition
+this._muxSession!.muxName
+```
+
+### Fix
+
+Add null guards before assertions, or document invariants:
+```typescript
+// Before:
+this._mux!.backend
+
+// After:
+if (!this._mux) throw new Error('Invariant: _mux must be initialized before startInteractive');
+this._mux.backend
+```
+
+### Positive Notes
+
+- **0 instances of `as any`**
+- **0 instances of `@ts-ignore` or `@ts-expect-error`**
+- TypeScript overall score: 8.5/10
+
+---
+
+## 16. Low: Dead Utility Functions
+
+**File**: `src/utils/string-similarity.ts`
+**Severity**: LOW
+**Impact**: Code clutter, confusion about what's actually used.
+
+### Unused Functions
+
+These are defined and exported but **never imported anywhere**:
+- `isSimilar(a, b, threshold)` - similarity check with threshold
+- `isSimilarByDistance(a, b, maxDistance)` - Levenshtein-based check
+- `levenshteinDistance(a, b)` - raw edit distance
+- `normalizePhrase(phrase)` - phrase normalization
+
+### Actually Used
+
+Only these are imported from the barrel:
+- `stringSimilarity()` - used in ralph-tracker.ts
+- `fuzzyPhraseMatch()` - used in ralph-tracker.ts
+- `todoContentHash()` - used in ralph-tracker.ts
+
+### Fix
+
+Delete unused functions or mark as `@internal` if kept for future use.
+
+---
+
+## 17. Low: No Dependency Injection for File I/O
+
+**Severity**: LOW (practical impact limited at current scale)
+**Impact**: Can't mock filesystem for unit tests. 68+ hard-coded filesystem calls.
+
+### Examples
+
+```typescript
+// state-store.ts - directly imports and uses fs
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+
+// push-store.ts - hard-coded paths
+const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
+const SUBS_FILE = join(DATA_DIR, 'push-subscriptions.json');
+
+// ai-checker-base.ts - direct execSync
+execSync(`tmux kill-session -t "${this.checkMuxName}"`, { timeout: 3000 });
+```
+
+### Why This Is Lower Priority
+
+- The codebase uses integration tests (spawning real processes/tmux sessions) rather than unit tests
+- Most filesystem operations are in infrastructure code, not business logic
+- Adding DI would be a large refactor with limited near-term benefit
+
+---
+
+## 18. Scorecard & Prioritized Roadmap
+
+### Overall Scores (Post-Implementation)
+
+| Category | Before | After | Notes |
+|----------|--------|-------|-------|
+| TypeScript Safety | 8.5/10 | 9/10 | 0 `any`, 0 `@ts-ignore`, Zod `z.infer` eliminates type drift |
+| Error Handling | 8/10 | 8/10 | Unchanged — already strong |
+| Async/Promise Safety | 9.5/10 | 9.5/10 | Unchanged — already strong |
+| Resource Cleanup | 7/10 | 8/10 | CleanupManager adopted in server.ts, subagent-watcher, bash-tool-parser; Debouncer in 6 files. **Gaps**: respawn-controller (10+ manual timers) and ralph-tracker (2 manual timers) not migrated |
+| Module Organization | 5/10 | 8/10 | Routes extracted (12 modules), types split (14 domain files), domain files split (ralph: 7, respawn: 5, session: 6) |
+| Test Coverage | 6/10 | 7.5/10 | Shared mock infrastructure, 12 route test files, MockSession/MockStateStore consolidated |
+| Config Centralization | 6/10 | 9/10 | 9 config files, ~65 constants centralized, 0 cross-file duplicates |
+| Frontend Architecture | 4/10 | 7/10 | 8 extracted modules (3,453 LOC), app.js reduced 24% (15.2K → 11.5K), xterm-zerolag-input vendor build |
+| Code Duplication | 5/10 | 8/10 | Debouncer utility, shared test mocks, barrel exports, config consolidation |
+
+### Implementation Phases
+
+**Phase 1 - Quick Wins (1-2 days)** ✅ COMPLETE
+1. ✅ Export missing functions from utils barrel (~30 min) — `createAnsiPatternFull`, `createAnsiPatternSimple`, `SAFE_PATH_PATTERN`, `validateTokenCounts`, `validateTokensAndCost` all now exported from `src/utils/index.ts`
+2. ✅ Delete dead utility functions (~15 min) — `isSimilar()` removed from `string-similarity.ts`; `levenshteinDistance()`, `isSimilarByDistance()`, `normalizePhrase()` made private (used internally by `fuzzyPhraseMatch`/`stringSimilarity`)
+3. ✅ Consolidate duplicated `EXEC_TIMEOUT_MS` constant (~15 min) — Created `src/config/exec-timeout.ts` as single source of truth; `claude-cli-resolver.ts`, `opencode-cli-resolver.ts`, and `tmux-manager.ts` all import from it
+4. ✅ Add `z.infer` to Zod schemas (~2 hours) — `src/web/schemas.ts` now has 36 `z.infer` type exports (lines 512-547) covering all schemas
+5. ✅ Fix 10 weak "not.toThrow()" tests (~1 hour) — All `not.toThrow()` calls now have behavior assertions: `task-tracker.test.ts` (6 instances all followed by state checks), `image-watcher.test.ts` (1 instance followed by length check), `session-manager.test.ts` (1 instance followed by count check)
+
+**Phase 2 - CleanupManager & Debounce (2-3 days)** ✅ COMPLETE
+1. ✅ Create `Debouncer` utility class (~1 hour) — Created `src/utils/debouncer.ts` with `Debouncer` and `KeyedDebouncer` classes; exported from `src/utils/index.ts`
+2. ✅ Migrate all 8 files from manual debounce to Debouncer — `state-store.ts` (2 Debouncers), `push-store.ts` (1 Debouncer), `bash-tool-parser.ts` (1 Debouncer), `image-watcher.ts` (1 KeyedDebouncer), `subagent-watcher.ts` (2 KeyedDebouncers), `server.ts` (1 KeyedDebouncer for persist timers), `ralph-tracker.ts` (2 Debouncers replacing 4 manual fields: `_todoUpdateTimer`, `_loopUpdateTimer`, `_todoUpdatePending`, `_loopUpdatePending`)
+3. ✅ Migrate respawn-controller to CleanupManager — 10 manual timer fields replaced with single `CleanupManager` instance + `timerIds` Map. `startTrackedTimer()`/`cancelTrackedTimer()` preserved as wrappers for UI countdown display and timer events. `clearTimers()` uses dispose-and-recreate pattern for state transitions.
+4. ✅ Migrate server.ts timer cleanup to CleanupManager (~2 hours) — `private cleanup = new CleanupManager()` present; terminal batch timers and pending respawn starts left as manual Maps (complex lifecycle)
+5. ✅ Migrate remaining files — `bash-tool-parser.ts` (CleanupManager ✅), `subagent-watcher.ts` (CleanupManager ✅), `ralph-tracker.ts` (Debouncer ✅)
+
+**Phase 3 - server.ts Route Extraction (3-4 days)** ✅ COMPLETE
+1. ✅ Created `src/web/routes/` with 12 domain route modules + index barrel (4,090 LOC total): session (909), system (768), ralph (533), plan (459), respawn (315), case, file, hook-event, mux, push, scheduled, team
+2. ✅ Created `src/web/middleware/auth.ts` (193 LOC) — Basic Auth, session cookies, rate limiting, security headers, CORS
+3. ✅ Created `src/web/ports/` with 7 typed port interfaces (142 LOC) — SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort, AuthPort; routes declare dependencies via intersection types
+4. ✅ Created `src/web/route-helpers.ts` (154 LOC) — `findSessionOrFail()`, `formatUptime()`, `sanitizeHookData()`, `autoConfigureRalph()`
+5. ✅ Reduced `server.ts` from 6,736 → 2,697 LOC (60% reduction). Remaining LOC is justified infrastructure: session lifecycle, SSE broadcast engine, terminal batching, respawn integration, resource cleanup
+
+**Phase 4 - Domain File Splitting (2-3 days)** ✅ COMPLETE
+1. ✅ Split `types.ts` into `src/types/` directory — 14 domain files (1,469 LOC total): common, session, task, app-state, respawn, ralph, api, lifecycle, run-summary, tools, teams, push, plan + index barrel. Original `types.ts` is now a 1-line re-export
+2. ✅ Split `ralph-tracker.ts` into 7 files (exceeded plan of 4) — ralph-tracker (2,391), ralph-plan-tracker (477), ralph-status-parser (552), ralph-fix-plan-watcher (366), ralph-stall-detector (166), ralph-config (153), ralph-loop (522)
+3. ✅ Split `respawn-controller.ts` into 5 files (exceeded plan of 3) — respawn-controller (3,228), respawn-health (229), respawn-metrics (229), respawn-patterns (131), respawn-adaptive-timing (134)
+4. ✅ Split `session.ts` into 6 files (exceeded plan of 3) — session (2,168), session-manager (298), session-auto-ops (284), session-cli-builder (132), session-task-cache (101), session-lifecycle-log (114)
+
+**Phase 5 - Frontend Modularization (3-4 days)** ✅ COMPLETE
+1. ✅ Extracted `constants.js` (238 LOC) — shared constants, timing values, Z-index layers, `escapeHtml()`, `extractSyncSegments()`
+2. ✅ Extracted `mobile-handlers.js` (449 LOC) — `MobileDetection`, `KeyboardHandler`, `SwipeHandler`
+3. ✅ Extracted `voice-input.js` (853 LOC) — `DeepgramProvider`, `VoiceInput`
+4. ✅ Extracted `notification-manager.js` (445 LOC) — `NotificationManager` class (5-layer system)
+5. ✅ Extracted `keyboard-accessory.js` (279 LOC) — `KeyboardAccessoryBar`, `FocusTrap`
+6. ✅ Extracted `api-client.js` (70 LOC) — `_api()`, `_apiJson()`, `_apiPost()`, `_apiPut()`
+7. ✅ Extracted `subagent-windows.js` (1,119 LOC) — 13 subagent window methods
+8. ✅ Removed inlined xterm-zerolag-input copy → built to `vendor/xterm-zerolag-input.js` from `packages/xterm-zerolag-input/`
+9. ✅ Reduced `app.js` from ~15,200 → 11,473 LOC (24% reduction). All scripts loaded in correct dependency order in `index.html`
+
+**Phase 6 - Config Consolidation (1 day)** ✅ COMPLETE
+1. ✅ Created 6 new domain-focused config files (better than plan's 2 generic files): `server-timing.ts` (13 constants), `auth-config.ts` (5 constants), `tunnel-config.ts` (8 constants), `terminal-limits.ts` (4 constants), `ai-defaults.ts` (3 constants), `team-config.ts` (3 constants)
+2. ✅ Total: 9 config files in `src/config/`, ~65 constants centralized
+3. ✅ Eliminated all cross-file duplicates: `STATS_COLLECTION_INTERVAL_MS` (was in 2 files), `timeout: 10000` (was 6× inline in hooks-config.ts → `HOOK_TIMEOUT_MS`), AI model string (was in 5 files → `AI_CHECK_MODEL`), `MAX_TRACKED_AGENTS` (was shadowed in subagent-watcher.ts)
+4. ✅ CLAUDE.md updated with config files table, import conventions, resource limits references
+
+**Phase 7 - Test Infrastructure (2-3 days)** ✅ COMPLETE
+1. ✅ Created `test/mocks/` directory with 5 files (541 LOC): `mock-session.ts` (312), `mock-state-store.ts` (60), `mock-route-context.ts` (121), `test-helpers.ts` (37), `index.ts` (11 — barrel export)
+2. ✅ Consolidated MockSession into single shared definition — no duplicate class definitions remain (2 `vi.mock()`-based copies intentionally left in session-manager.test.ts and ralph-loop.test.ts)
+3. ✅ `respawn-test-utils.ts` converted to backward-compatibility shim — re-exports from `test/mocks/`, retains respawn-specific utilities (MockAiIdleChecker, TimeController, etc.)
+4. ✅ Created initial 3 route test files with 58 total tests: `session-routes.test.ts` (34 tests), `respawn-routes.test.ts` (13 tests), `system-routes.test.ts` (11 tests). Route test harness uses `app.inject()` — no real ports needed
+5. ✅ All 12 route modules now have dedicated test files in `test/routes/`: session, respawn, system, ralph, plan, push, team, mux, file, scheduled, hook-event, case
+
+---
+
+## Appendix: File Size Inventory (Post-Implementation)
+
+### Before vs After
+
+| File | Before | After | Change |
+|------|--------|-------|--------|
+| `src/web/server.ts` | 6,736 | 2,697 | **−60%** (routes, auth, ports extracted) |
+| `src/web/public/app.js` | 15,196 | 11,473 | **−24%** (8 modules extracted) |
+| `src/ralph-tracker.ts` | 3,905 | 2,391 | **−39%** (6 companion files extracted) |
+| `src/respawn-controller.ts` | 3,611 | 3,228 | **−11%** (4 companion files extracted) |
+| `src/session.ts` | 2,418 | 2,168 | **−10%** (5 companion files extracted) |
+| `src/types.ts` | 1,443 | 1 | **−99%** (14 domain files in `src/types/`) |
+
+### New Infrastructure Created
+
+| Directory | Files | Total LOC | Purpose |
+|-----------|-------|-----------|---------|
+| `src/web/routes/` | 13 | 4,090 | Domain route modules |
+| `src/web/ports/` | 7 | 142 | Port interfaces for DI |
+| `src/web/middleware/` | 1 | 193 | Auth middleware |
+| `src/types/` | 14 | 1,469 | Domain type files |
+| `src/config/` | 9 | ~450 | Centralized config |
+| `test/mocks/` | 5 | 541 | Shared test mocks |
+| `test/routes/` | 4 | ~500 | Route handler tests |
+
+### Extracted Frontend Modules
+
+| Module | Lines | Purpose |
+|--------|-------|---------|
+| `subagent-windows.js` | 1,119 | Subagent window management |
+| `voice-input.js` | 853 | DeepgramProvider, VoiceInput |
+| `mobile-handlers.js` | 449 | MobileDetection, KeyboardHandler, SwipeHandler |
+| `notification-manager.js` | 445 | 5-layer notification system |
+| `keyboard-accessory.js` | 279 | KeyboardAccessoryBar, FocusTrap |
+| `constants.js` | 238 | Shared constants, timing, Z-index |
+| `api-client.js` | 70 | API fetch wrapper |
+
+### What's Working Well
+
+These patterns should be **preserved, not refactored**:
+- Clean one-way dependency graph (no circular deps)
+- EventEmitter-based decoupling between domain models
+- Proper `import type` usage (19 files, consistent)
+- Utility type adoption (101 instances of Record, Partial, Omit, etc.)
+- `assertNever()` for exhaustive switch checking
+- `StaleExpirationMap` and `LRUMap` for bounded collections
+- State persistence circuit breaker pattern
+- TypeScript strict mode with all safety flags enabled
+- `CleanupManager` for centralized timer/watcher disposal
+- `Debouncer`/`KeyedDebouncer` for consistent debounce patterns
+- Port interfaces for route module dependency injection
+- `Object.assign(CodemanApp.prototype, ...)` for frontend module composition

docs/archive/performance-analysis.md

@@ -0,0 +1,423 @@
+# Performance Analysis & Optimization Opportunities
+
+**Date**: 2026-03-07
+**Scope**: Full-stack performance analysis — backend PTY handling, SSE broadcasting, frontend terminal rendering, local echo overlay, DOM updates, config/scaling limits.
+**Constraint**: All recommendations preserve existing functionality including local echo, backpressure, anti-flicker pipeline, and mobile support.
+
+---
+
+## Executive Summary
+
+The codebase is already well-optimized in critical paths. The multi-layer backpressure system, adaptive terminal batching, DEC 2026 sync markers, and incremental state serialization are strong. The main opportunities are in **reducing unnecessary work** (SSE filtering, DOM rebuilds, lazy terminal init) rather than algorithmic changes.
+
+**Top 5 high-impact opportunities:**
+
+| # | Optimization | Impact | Risk | Effort |
+|---|-------------|--------|------|--------|
+| 1 | Session-scoped SSE subscriptions | Bandwidth -60-80%, CPU -40% | Medium | Medium |
+| 2 | Lazy xterm.js for minimized subagent windows | Memory -3.5MB at 50 agents | Low | Low |
+| 3 | Targeted badge update (skip full tab rebuild) | Eliminates O(n) reflow on badge change | Low | Low |
+| 4 | Conditional SSE padding (tunnel-only, terminal-only) | Bandwidth -70% when tunneled | Low | Low |
+| 5 | Canvas renderer on mobile | GPU pressure reduction, battery savings | Low | Low |
+
+---
+
+## 1. SSE Broadcasting
+
+### Current State
+- **92 event types** broadcast to all connected clients (max 100)
+- Single `JSON.stringify()` per event, shared across all clients (efficient)
+- **No per-client filtering** — every client receives every event regardless of which session they're viewing
+- 8KB padding appended to **every** event when tunnel is active (forces Cloudflare proxy flush)
+- Backpressure: clients marked as backpressured if `reply.raw.write()` returns false; recovery via `session:needsRefresh`
+
+### Bottlenecks
+
+**B1: No session-scoped SSE subscriptions** (`server.ts:1986`)
+- Client viewing session A still receives all events for sessions B through T
+- With 20 active sessions, ~95% of terminal events are irrelevant to any given client
+- Cost: wasted bandwidth, CPU for JSON parsing, and event handler dispatch on client
+
+**B2: Unconditional 8KB padding** (`server.ts:1977`)
+- Every event gets 8KB comment padding when tunnel is active
+- A `task:updated` event (~200 bytes payload) becomes ~8.2KB
+- High-frequency events like `session:terminal` need the padding; low-frequency events like `session:created` don't
+
+### Recommendations
+
+**R1: Session-scoped SSE subscriptions** (High impact)
+- Add `?sessions=id1,id2` query param to `/api/events` SSE endpoint
+- Server filters events by session ID before broadcasting
+- Client subscribes to active session + "global" events (session lifecycle, system)
+- Re-subscribes on tab switch (or subscribe to all with client-side filter as fallback)
+- **Savings**: ~80% bandwidth reduction for single-session viewers; ~60% for multi-session dashboards
+
+**R2: Tiered SSE padding** (Medium impact)
+- Only pad `session:terminal` events and SSE heartbeats (the two that need proxy flush)
+- Skip padding for low-frequency structural events (`session:created`, `task:updated`, etc.)
+- **Savings**: ~70% padding overhead reduction; terminal events already large enough to flush
+
+---
+
+## 2. Terminal Rendering
+
+### Current State (Well-Optimized)
+- **6-layer anti-flicker pipeline**: Server batching (adaptive 16-50ms) → DEC 2026 sync wrap → single JSON serialize → client rAF batching → sync segment parser → chunked buffer loading (32KB/frame)
+- **64KB/frame write budget** with DEC 2026 sync-segment awareness (prevents 141KB single-frame freezes)
+- **3-layer backpressure**: SSE cap (128KB queued → drop + refresh), frame budget (64KB/frame), chunked restore (32KB/frame)
+- WebGL renderer enabled by default with canvas fallback on context loss
+- Typical latency: 16-32ms; worst case: ~115ms (50ms server batch + 50ms sync wait + 16ms rAF)
+
+### Bottlenecks
+
+**B3: WebGL on mobile** (`app.js:627-637`)
+- Mobile GPUs are weaker; WebGL context loss more likely on low-end devices
+- Canvas renderer is sufficient for mobile (typically 1 session, smaller viewport)
+
+**B4: Static scrollback for all sessions** (`app.js:572`)
+- Default 5000 lines scrollback for all sessions regardless of activity level
+- Heavy output sessions (build logs, test runners) accumulate large scroll buffers
+
+**B5: No addon lazy loading**
+- FitAddon, Unicode11Addon, and WebGLAddon all loaded at terminal init
+- Unicode11Addon only needed for CJK content; WebGLAddon is large
+
+### Recommendations
+
+**R3: Force canvas renderer on mobile** (Low risk)
+- Detect `MobileDetection.isMobile()` and skip WebGL addon loading
+- Reduces GPU memory pressure, prevents context loss crashes
+- Mobile typically has 1-2 sessions — canvas performance is more than adequate
+
+**R4: Dynamic scrollback based on session activity** (Low risk)
+- Active sessions (working state): 5000 lines (current default)
+- Inactive/idle sessions: reduce to 2000 lines
+- Restore on session select (fetch from server buffer)
+- **Savings**: ~60% scrollback memory for idle sessions
+
+**R5: Lazy-load Unicode11Addon** (Low risk)
+- Only load when CJK content is detected in terminal output
+- Detection: check for characters in CJK Unicode ranges during ANSI stripping (already iterating)
+- Most sessions never need it
+
+---
+
+## 3. DOM & Session Tab Rendering
+
+### Current State
+- Session tabs use **intelligent incremental updates** with debounced 100ms rendering
+- Incremental path: only updates changed properties (classes, textContent, badges) when session list is stable
+- Full rebuild path: triggered when sessions added/removed **or badge count changes**
+- Subagent windows: per-window xterm.js instances, even when minimized
+
+### Bottlenecks
+
+**B6: Badge count change triggers full tab rebuild** (`app.js:3207-3209`)
+- A single subagent badge increment on one tab triggers `_fullRenderSessionTabs()` — rebuilds entire sidebar HTML via `innerHTML =`
+- With 20 sessions, this is an O(n) reflow for a single badge number change
+- Badge changes are frequent during active subagent work
+
+**B7: Minimized subagent windows retain xterm.js instances** (`subagent-windows.js`)
+- 50 subagent windows × ~75KB per xterm.js instance = ~3.75MB DOM memory
+- Minimized windows are invisible but their terminals remain in DOM
+- xterm.js instances continue processing resize events even when hidden
+
+**B8: `backdrop-filter: blur()` on overlays** (`styles.css:2246-2247, 3098`)
+- Forces new stacking context, disables browser compositing optimizations
+- 50-100ms layout thrashing on modal open/close
+- Only 2 uses, but they're on frequently toggled overlays
+
+### Recommendations
+
+**R6: Targeted badge update without full rebuild** (Low risk)
+- When badge count changes but session list is stable, update only the badge `<span>` textContent
+- Keep incremental path for badge changes; only use full rebuild for structural changes (add/remove sessions)
+- **Savings**: Eliminates O(n) reflow per badge change; reduces to O(1) targeted update
+
+**R7: Lazy xterm.js initialization for subagent windows** (Medium impact)
+- Only create xterm.js Terminal instance when window is restored/maximized
+- On minimize: serialize terminal buffer, dispose Terminal instance, keep buffer in memory
+- On restore: create new Terminal, write buffer back
+- **Savings**: ~3.5MB DOM reduction at 50 minimized agents; eliminates hidden resize processing
+- **Trade-off**: ~200-500ms restore delay (buffer write), mitigated by chunked loading
+
+**R8: Replace `backdrop-filter: blur()` with `background: rgba()`** (Low risk)
+- Use semi-transparent background instead of blur effect
+- Or use `will-change: transform` hint if blur is kept
+- **Savings**: Eliminates forced recomposition layer; 50-100ms faster overlay open
+
+---
+
+## 4. Backend PTY & State Management
+
+### Current State (Excellent)
+- **BufferAccumulator**: Array-based chunking with lazy join on read — avoids O(n) string concatenation
+- **ANSI stripping**: Throttled at 150ms intervals with lazy evaluation (not per-chunk)
+- **State persistence**: 500ms debounce + incremental JSON caching per session (only dirty sessions re-serialized)
+- **Expensive parsers**: Throttled to 150ms window, accumulated data capped at 64KB
+- **Memory**: All buffers have hard limits (2MB terminal, 1MB text, 1000 messages, 64KB line buffer)
+
+### Bottlenecks
+
+**B9: Pending clean data cap at 64KB** (`session.ts:1097-1133`)
+- Between 150ms processing windows, raw PTY data accumulates in `_pendingCleanData`
+- Capped at 64KB — excess data rolls off (old data discarded)
+- During heavy output (large build logs), this means parsers may miss content
+- Acceptable trade-off for performance, but worth documenting
+
+**B10: `LRUMap.delete()` is O(n) worst case** (`utils/lru-map.ts:137-138`)
+- When deleting the newest entry, iterates all keys to find new newest
+- Rare in practice (delete is uncommon; set/get are hot paths)
+- Could matter during mass cleanup of 500 agents
+
+### Recommendations
+
+**R9: Consider adaptive pending data cap** (Low priority)
+- During idle detection (critical to get right), increase cap to 128KB
+- During active working state, keep at 64KB (parsers less critical)
+- **Benefit**: More accurate idle detection during heavy output
+
+**R10: Track second-newest in LRUMap** (Low priority)
+- Maintain a `_secondNewestKey` alongside `_newestKey`
+- On delete of newest, promote second-newest without iteration
+- Only matters at scale (500+ agents with frequent eviction)
+
+---
+
+## 5. Local Echo & Input Path
+
+### Current State (Well-Designed)
+- **DOM overlay approach** — `<span>` elements in `.xterm-screen` at z-index 7, completely independent of `terminal.write()`
+- **Render caching**: `_lastRenderKey` includes text, position, column offsets — skips redundant re-renders
+- **Input flow**: Char accumulation → Enter triggers flush → 80ms delay before `\r` (ensures text reaches PTY first)
+- **Tab completion**: Baseline snapshot → detect buffer change → 300ms fallback timer
+- **CJK support**: Per-character width detection with `terminal.unicode.getStringCellWidth()` preferred, manual fallback
+- **Prompt detection**: Bottom-up line scan, O(rows) — cached position, column-lock prevents jitter
+
+### Bottlenecks
+
+**B11: tmux send-keys latency** (~50-100ms per input)
+- Each `writeViaMux()` spawns a child process (`tmux send-keys`)
+- Text and Enter sent separately with 50ms delay between
+- For rapid typing: characters batch before Enter, so overhead is per-command not per-keystroke
+- **Acceptable trade-off** for session persistence (tmux survives server restarts)
+
+**B12: 80ms delay between text flush and Enter** (`app.js:872-875`)
+- Intentional: ensures text reaches PTY before Enter, preventing Ink from processing empty input
+- Adds 80ms to perceived Enter-to-response latency
+- Could potentially be reduced with acknowledgment-based approach
+
+**B13: Scroll listener on terminal viewport** (`zerolag-input-addon.ts:139`)
+- 50ms debounced re-render on scroll — acceptable but fires frequently during heavy output
+- Overlay hidden when scrolled up (correct behavior), shown when at bottom
+
+### Recommendations
+
+**R11: Reduce Enter delay from 80ms to 50ms** (Low risk, test carefully)
+- The tmux `send-keys` already has 50ms internal delay
+- Combined with network latency, 80ms client-side may be excessive
+- Test with Ink-heavy sessions (Claude Code's status bar) — if text arrives before Enter at 50ms, reduce
+- **Savings**: 30ms perceived latency reduction per command
+
+**R12: Batch tmux send-keys via stdin pipe** (Medium effort, high impact for rapid input)
+- Instead of spawning `tmux send-keys` per input, maintain a persistent connection
+- Use `tmux -C` (control mode) for programmatic interaction without child process spawning
+- **Savings**: Eliminate ~50-100ms process spawn overhead per input
+- **Risk**: Control mode has different semantics; needs careful testing with session persistence
+
+**R13: Skip overlay re-render during heavy output scroll** (Low risk)
+- When terminal is receiving >10KB/s output, hide overlay entirely (user isn't typing during heavy output)
+- Re-show overlay after 500ms of output silence
+- **Savings**: Eliminates unnecessary DOM overlay re-renders during build logs / test output
+
+---
+
+## 6. Polling & File Watchers
+
+### Current State
+- **SubagentWatcher**: 1s base poll, full scan throttled to every 5s, fs.watch() on known directories
+- **TranscriptWatcher**: 1 per session, fs.watch() primary with 1s poll fallback
+- **ImageWatcher**: chokidar per session with 100ms stability poll, burst limit 20/10s
+- **TeamWatcher**: chokidar primary with 30s poll fallback, LRU caches (50 teams, 200 tasks)
+- **RalphTracker**: Todo cleanup every 5 minutes
+
+### Scaling Profile (20 sessions)
+| Component | Instances | Frequency | Total ops/sec |
+|-----------|-----------|-----------|---------------|
+| SubagentWatcher | 1 (global) | Full scan every 5s | 0.2/s |
+| TranscriptWatcher | 20 | 1s poll (fallback) | 20/s max |
+| ImageWatcher | 20 | 100ms poll (during writes only) | 200/s burst |
+| TeamWatcher | 1 (global) | 30s poll (fallback) | 0.03/s |
+| SSE heartbeat | 1 (global) | 15s | 0.07/s |
+| SSE dead client check | 1 (global) | 30s | 0.03/s |
+| Mux stats collection | 1 (global) | 2s | 0.5/s |
+| **Total steady-state** | | | **~21/s** |
+
+### Recommendations
+
+**R14: Increase TranscriptWatcher poll interval to 2s** (Low risk)
+- Transcript changes are infrequent (new messages every few seconds at most)
+- fs.watch() is the primary mechanism; polling is fallback
+- **Savings**: Halves fallback filesystem checks (20/s → 10/s for 20 sessions)
+
+**R15: Share chokidar instances for co-located session directories** (Medium effort)
+- Sessions in the same parent directory could share a single chokidar watcher with depth:3
+- Common case: multiple sessions in `~/projects/foo/` — one watcher covers all
+- **Savings**: Reduce chokidar instances from 20 to ~5-10 for typical workloads
+
+---
+
+## 7. Frontend Asset Delivery
+
+### Current State
+- **app.js**: 12,027 lines (source) → esbuild minified → gzip/brotli compressed (~30-40KB gzipped)
+- **Static caching**: `maxAge: '1y'` via `@fastify/static`
+- **Service worker**: Push notification handler only — no asset caching
+- **No code splitting**: Single monolithic app.js bundle
+
+### Bottlenecks
+
+**B14: No cache-busting mechanism**
+- `maxAge: '1y'` means browsers cache aggressively
+- After deployment, users need `Ctrl+Shift+R` to see updates
+- No content hash in filenames or ETags for automatic invalidation
+
+**B15: Monolithic app.js**
+- All 12K lines loaded on initial page load regardless of which features are used
+- Ralph wizard, plan orchestrator UI, team management — all loaded upfront
+- Mobile loads the same bundle as desktop
+
+### Recommendations
+
+**R16: Add content hash to asset filenames** (Medium impact)
+- Build step: rename `app.js` → `app.[hash].js`
+- Generate a manifest or inject hash into HTML template
+- Keep `maxAge: '1y'` — cache invalidation happens via filename change
+- **Savings**: Eliminates stale cache issues after deployment; removes need for manual hard refresh
+
+**R17: Code-split app.js into core + feature modules** (High effort, medium impact)
+- Core (~4K lines): terminal, SSE, session management, tabs, input handling
+- Deferred (~8K lines): Ralph wizard, plan UI, team management, subagent windows, image viewer
+- Load deferred modules on first use via dynamic `import()` or lazy `<script>` injection
+- **Savings**: ~60% reduction in initial load size; faster time-to-interactive
+- **Risk**: Complexity increase; need to handle loading states for deferred features
+- **Note**: May not be worth the effort given the app is already gzipped to ~30-40KB
+
+---
+
+## 8. CSS Performance
+
+### Current State
+- **styles.css**: 7,153 lines with ~45 box-shadow uses, 2 backdrop-filter uses
+- Animations: GPU-accelerated keyframes for pulsing alerts, loading spinners
+- Z-index layering: well-organized (subagent 1000, plan 1100, log 2000, image 3000, overlay 7)
+
+### Recommendations
+
+**R18: Replace backdrop-filter with opaque overlay** (Low risk, covered in R8)
+
+**R19: Use `contain: content` on subagent windows** (Low risk)
+- Add CSS containment to subagent window containers
+- Prevents layout changes inside windows from triggering reflow on parent
+- Especially valuable with 50 windows: changes in one window won't invalidate others
+- ```css
+  .subagent-window { contain: content; }
+  ```
+- **Savings**: Reduces layout recalculation scope from global to per-window
+
+**R20: Use `content-visibility: auto` on off-screen subagent windows** (Low risk)
+- Browser skips rendering of off-screen windows entirely
+- Combined with `contain-intrinsic-size` to prevent layout shift
+- ```css
+  .subagent-window.minimized { content-visibility: hidden; }
+  ```
+- **Savings**: Browser skips paint/layout for minimized windows; complements R7
+
+---
+
+## 9. Memory & Scaling Limits
+
+### Current Budget (20 sessions)
+| Component | Per Session | Total | Status |
+|-----------|-----------|-------|--------|
+| Terminal buffer | 2MB | 40MB | Hard-limited, auto-trim |
+| Text output | 1MB | 20MB | Hard-limited, auto-trim |
+| Messages | ~1MB | 20MB | Capped at 1000, trims to 800 |
+| Respawn buffer | 1MB | 20MB | Hard-limited |
+| **Buffers total** | | **100MB** | Acceptable |
+| TranscriptWatcher | ~100KB | 2MB | |
+| ImageWatcher | ~50KB | 1MB | |
+| SubagentWatcher | ~500KB | 500KB | Global |
+| Frontend terminal cache | ~256KB | 5MB | LRU, max 20 entries |
+| **Total estimated** | | **~110MB** | Comfortable |
+
+### At Max Scale (50 sessions)
+- Buffers: ~250MB
+- Watchers: ~5MB
+- **Total: ~255MB** + Node.js overhead — acceptable on modern hardware
+
+### Potential Leak Vectors (All Mitigated)
+- `_shortIdCache` in server — unbounded Map, but entries are tiny (string→string); grows at O(sessions created), not O(events)
+- All CleanupManager-registered resources tracked and disposed on session stop
+- `isStopped` guard prevents new timers after session cleanup
+
+---
+
+## 10. Implementation Priority Matrix
+
+### Phase 1 — Quick Wins (1-2 hours each, low risk)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R6 | Targeted badge update | `app.js` (3207-3209) |
+| R3 | Canvas renderer on mobile | `app.js` (627-637) |
+| R8 | Replace backdrop-filter blur | `styles.css` (2246, 3098) |
+| R19 | CSS containment on subagent windows | `styles.css` |
+| R20 | `content-visibility: hidden` on minimized windows | `styles.css` |
+
+### Phase 2 — Medium Effort (half-day each)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R2 | Tiered SSE padding | `server.ts` (broadcast function) |
+| R7 | Lazy xterm.js for minimized subagents | `subagent-windows.js` |
+| R11 | Reduce Enter delay to 50ms | `app.js` (872-875), test with Ink |
+| R14 | TranscriptWatcher 2s poll | `transcript-watcher.ts` |
+| R16 | Content-hash asset filenames | `build.mjs`, `server.ts` |
+
+### Phase 3 — Larger Initiatives (1-2 days each)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R1 | Session-scoped SSE subscriptions | `server.ts`, `app.js` (SSE connect) |
+| R5 | Lazy Unicode11Addon loading | `app.js`, build pipeline |
+| R12 | Persistent tmux control mode | `tmux-manager.ts` |
+| R17 | Code-split app.js | `app.js`, `build.mjs`, HTML template |
+
+### Not Recommended (Low ROI or High Risk)
+| # | Why Not |
+|---|---------|
+| R4 | Dynamic scrollback adds complexity; memory savings marginal vs total budget |
+| R9 | Adaptive pending data cap adds state; current 64KB cap rarely matters |
+| R10 | LRUMap.delete() O(n) is theoretical; never triggered at current scale |
+| R15 | Shared chokidar instances add directory-matching complexity for minimal gain |
+
+---
+
+## Appendix: Key File Locations
+
+| Area | File | Key Lines |
+|------|------|-----------|
+| SSE broadcast | `src/web/server.ts` | 1961-1989 (broadcast), 1934-1959 (backpressure) |
+| Terminal batching | `src/web/server.ts` | 1994-2048 (per-session adaptive batching) |
+| Frame budget | `src/web/public/app.js` | 1370-1478 (flushPendingWrites, 64KB cap) |
+| Flicker filter | `src/web/public/app.js` | 1176-1255 (50ms sync wait, 256KB safety) |
+| Tab rendering | `src/web/public/app.js` | 3108-3357 (incremental + full rebuild) |
+| Tab switching | `src/web/public/app.js` | 3560-3760 (cache + chunked load + deferred UI) |
+| Local echo | `packages/xterm-zerolag-input/src/` | All files (overlay, prompt, CJK) |
+| Local echo integration | `src/web/public/app.js` | 640, 815-988 (input flow) |
+| Subagent windows | `src/web/public/subagent-windows.js` | Full file (window mgmt, drag, minimize) |
+| State persistence | `src/state-store.ts` | 161-250 (debounced save, incremental JSON) |
+| Buffer accumulator | `src/utils/buffer-accumulator.ts` | Full file (array chunks, lazy join) |
+| PTY handling | `src/session.ts` | 1046-1133 (data flow), 1173-1230 (parsing) |
+| Config limits | `src/config/` | 9 files (buffer, map, timing, auth, etc.) |
+| Anti-flicker docs | `docs/terminal-anti-flicker.md` | Architecture reference |
+| CSS | `src/web/public/styles.css` | 2246 (backdrop-filter), full file |
+| Build pipeline | `scripts/build.mjs` | 59-68 (minify + compress) |

docs/archive/performance-optimization-plan.md

@@ -0,0 +1,168 @@
+# Performance & Responsiveness Optimization Plan
+
+**Date**: 2026-02-28
+**Status**: Phases 1–4 Complete. Phase 5 optional/deferred.
+
+---
+
+## Executive Summary
+
+Three independent research passes analyzed the Codeman codebase for performance bottlenecks across frontend rendering, backend hot paths, and system-level resource usage. The codebase already has strong foundational optimizations (per-session adaptive batching, rAF terminal writes, DEC 2026 sync markers, backpressure handling). This plan targets the remaining high-impact opportunities.
+
+**Key finding**: The biggest wins come from **skipping unnecessary work** — serializing unchanged state, processing output nobody is watching, and reducing broadcast volume.
+
+---
+
+## Phase 1: Quick Wins — COMPLETE
+
+All Phase 1 items were found to already exist in the codebase during verification:
+
+| # | Item | Status | Evidence |
+|---|------|--------|----------|
+| 1.1 | Skip terminal writes for hidden tabs | Done | SSE handler filters by `activeSessionId` (app.js:4076) |
+| 1.2 | mobile.css media query | Done | `media="(max-width: 1023px)"` on link tag (index.html:13) |
+| 1.3 | Deduplicate init API calls | Done | `_initGeneration` dedup + 3s fallback timer (app.js:2901-2904) |
+| 1.4 | Remove cache-busting timestamps | Done | No `?_t=` patterns found anywhere |
+| 1.5 | JS/CSS minification + compression | Done | esbuild minify + gzip + brotli in build.mjs (lines 42-51) |
+
+---
+
+## Phase 2: Frontend Responsiveness — COMPLETE
+
+### 2.1 Batch `getBoundingClientRect()` in connection lines — DONE
+- **Files**: `src/web/public/app.js` (`_updateConnectionLinesImmediate()`)
+- **Change**: Refactored to batch all layout reads into Phase 1 (collect all rects into a Map), then perform all SVG writes in Phase 2 using cached values. Classic read-then-write pattern prevents interleaved forced reflows.
+
+### 2.2 Clean up ResizeObservers — Already implemented
+- `forceCloseSubagentWindow()` disconnects observers (app.js:12618-12620)
+- `cleanupAllFloatingWindows()` disconnects all on reconnect (app.js:12649-12653)
+- Observer refs stored on `windowData.resizeObserver` (app.js:12492)
+
+### 2.3 Drag handler cleanup — Already implemented
+- `makeWindowDraggable()` returns listener refs, stored in `windowData.dragListeners`
+- `forceCloseSubagentWindow()` removes all document-level drag listeners (app.js:12622-12630)
+- Panel drags add listeners on mousedown, remove on mouseup (app.js:10253-10284)
+
+### 2.4 Mobile window position cache — Skipped
+- O(n) loop over max ~20 windows; complexity of cached counter not justified
+
+### 2.5 Lazy modal DOM — Skipped
+- Large effort, marginal benefit for a vanilla JS app with fast DOM construction
+
+---
+
+## Phase 3: Backend Hot Paths — COMPLETE
+
+### 3.1 State diff broadcasts — ALREADY OPTIMIZED
+- `broadcastSessionStateDebounced()` already batches at 500ms intervals
+- `toLightDetailedState()` excludes heavy buffers (textOutput, terminalBuffer)
+- Per-session serialization is <1ms; with debouncing, only 1-3 sessions serialize per flush
+- JSON.stringify happens once per broadcast (not per client) — serialization cost is negligible
+- Full state diffs would add significant frontend complexity for marginal gain
+
+### 3.2 Improve session list cache hit rate — DONE
+- **Files**: `src/web/server.ts` (`broadcast()` method)
+- **Change**: Cache now only invalidated on truly structural events (`session:created`, `session:deleted`, `session:updated`) instead of on every `session:*` and `respawn:*` event. High-frequency events like `session:working`, `session:idle`, `session:completion`, `respawn:stateChanged` no longer defeat the 1s TTL cache.
+- **Impact**: Cache hit ratio from ~0% to ~80%+ during active sessions. The debounced `session:updated` still refreshes the cache within 500ms of any state change.
+
+### 3.3 Skip PTY processing — ALREADY OPTIMIZED
+- `_processExpensiveParsers()` is already throttled to every 150ms (not per-chunk)
+- Lazy ANSI stripping via `getCleanData()` closure — only computed when a consumer needs it
+- Quick pre-checks skip parsers when content is irrelevant (e.g., token parser only runs if data contains "token")
+- OpenCode sessions skip all Claude-specific parsers entirely
+- Further optimization would require visibility-aware processing, adding complexity for marginal gain
+
+### 3.4 Batch subagent liveness checks — Deferred
+- `/proc/{pid}` stat calls are ~0.1ms each; even with 500 agents, total is 50ms every 10s
+- Current approach is simple and reliable; batching adds race condition risk
+- Consider only if profiling shows this as a bottleneck
+
+### 3.5 Deduplicate detection update emissions — DONE
+- **Files**: `src/respawn-controller.ts` (`startDetectionUpdates()`)
+- **Change**: Detection status now only emitted when key fields (confidenceLevel, statusText, controller state) actually change. Previously emitted every 2s regardless, broadcasting identical status to all SSE clients.
+- **Impact**: For stable/idle sessions, eliminates ~100% of redundant detection broadcasts. For active sessions, reduces broadcasts to only meaningful state transitions.
+
+---
+
+## Phase 4: System-Level Improvements — COMPLETE
+
+### 4.1 Incremental state persistence — DONE
+- **Files**: `src/state-store.ts` (`assembleStateJson()`, `setSession()`)
+- **Change**: Added `dirtySessions` Set and `cachedSessionJsons` Map. On persist, only dirty sessions are re-serialized; clean sessions reuse cached JSON fragments. `setSession()` marks sessions dirty; `assembleStateJson()` rebuilds only changed fragments.
+- **Impact**: Serialization cost reduced from O(all sessions) to O(dirty sessions). Typical steady-state: 1-2 dirty sessions instead of 50.
+
+### 4.2 Replace polling with fs watchers for team watcher — DONE
+- **Files**: `src/team-watcher.ts` (`setupFsWatchers()`)
+- **Change**: Added chokidar watchers on both `~/.claude/teams/` and `~/.claude/tasks/` directories for instant event-driven detection. Lock files ignored via chokidar config. Mtime-based dedup skips unchanged files. Polling interval relaxed from 5s to 30s as a fallback.
+- **Impact**: Near-instant team detection; polling overhead eliminated for normal operation.
+
+### 4.3 Consolidate subagent file watchers — DONE
+- **Files**: `src/subagent-watcher.ts` (`setupDirectoryWatcher()`)
+- **Change**: Replaced per-agent chokidar watchers with one `fs.watch()` per session subagent directory. Events are routed to the correct agent via filename. Per-file debouncing (100ms) prevents hammering on bulk discovery.
+- **Impact**: Inotify watchers reduced from potentially 500 (one per agent) to ~50 (one per session directory).
+
+### 4.4 Stream transcript files instead of full reads — DONE
+- **Files**: `src/subagent-watcher.ts` (`tailFile()`, `findDescriptionInAgentFile()`, parent transcript lookup)
+- **Change**: Multiple streaming strategies implemented:
+  - **Live monitoring**: Position-based `tailFile()` with `createReadStream({ start: fromPosition })` — only reads new content
+  - **Parent transcript lookup**: Streams only last 16KB (`createReadStream({ start: offset })`)
+  - **Description extraction**: Streams only first 8KB, exits early after 5 lines
+  - **Full read**: Only for on-demand transcript review panel (with optional `limit` parameter)
+- **Impact**: File I/O for bulk agent discovery reduced from ~50MB to ~5MB.
+
+---
+
+## Phase 5: Long-Term Architectural (Optional) — NOT STARTED
+
+These items are deferred until scaling demands justify the complexity.
+
+### 5.1 Worker thread for PTY processing
+- **Files**: `src/session.ts`
+- **Problem**: ANSI stripping, Ralph tracking, and bash tool parsing all run on the main event loop. At scale (50 busy sessions), this consumes 300-500ms CPU/sec.
+- **Fix**: Offload ANSI strip + line processing to a worker thread pool. Main thread receives clean text + parsed events.
+- **Impact**: Frees event loop for I/O operations. Most impactful at 10+ concurrent busy sessions.
+
+### 5.2 Per-session SSE subscriptions
+- **Files**: `src/web/server.ts`
+- **Problem**: Every SSE event is broadcast to all connected clients. A client watching session A still receives events for sessions B through Z.
+- **Fix**: Clients subscribe to specific session IDs. Server only sends events to interested clients.
+- **Impact**: Reduces SSE broadcast fan-out from N clients to ~1-2 per event. Major improvement at 100 SSE clients.
+
+### 5.3 O(1) LRUMap via doubly-linked list
+- **Files**: `src/utils/lru-map.ts` (~lines 98-110)
+- **Problem**: `get()` uses delete + re-insert to refresh position — O(n) on Map iteration for delete.
+- **Fix**: Implement classic LRU with doubly-linked list + Map for O(1) get/put/evict.
+- **Impact**: Low — current sizes (max 500) make this barely measurable. Only worthwhile if LRUMap is used on hot paths.
+
+---
+
+## Completion Summary
+
+| Phase | Scope | Status | Items |
+|-------|-------|--------|-------|
+| 1 | Quick Wins | **Complete** | 5/5 (all pre-existing) |
+| 2 | Frontend Responsiveness | **Complete** | 3/3 actionable done, 2 skipped |
+| 3 | Backend Hot Paths | **Complete** | 4/4 actionable done, 1 deferred |
+| 4 | System-Level | **Complete** | 4/4 done |
+| 5 | Long-Term Architectural | **Not started** | 0/3 — deferred until needed |
+
+**Overall**: 16/16 actionable items complete. 3 optional items deferred.
+
+---
+
+## Measurement
+
+Before starting Phase 5, establish baselines:
+
+1. **Frontend**: Record Chrome DevTools Performance trace with 10 sessions open. Measure:
+   - Frame rate during rapid terminal output
+   - Long tasks (>50ms) count per 30s
+   - Heap size after 1h session
+
+2. **Backend**: Add `performance.now()` instrumentation around:
+   - `flushSessionTerminalBatch()` — time per flush
+   - `broadcastSessionStateDebounced()` — serialization time
+   - `StateStore.save()` — persist time
+   - Event loop lag via `monitorEventLoopDelay()`
+
+3. **First load**: Lighthouse score on desktop and mobile (simulated 3G)

docs/archive/performance-plan.md

@@ -0,0 +1,74 @@
+# Codeman Performance Optimization Plan
+
+## Current State
+
+The backend is **already production-grade** — SSE broadcasting, state persistence, terminal batching, buffer management, and memory patterns are all well-optimized. The biggest gains are on the **frontend delivery** side.
+
+## Implemented Optimizations
+
+### 1. V8 Compile Cache (10-20% faster cold start)
+
+**Files:** `scripts/codeman-web.service`, `package.json`
+
+Node.js re-parses and compiles all JS on every cold start. `NODE_COMPILE_CACHE` caches V8 compiled bytecode to disk, reusing it on subsequent starts.
+
+- Added `Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache` to systemd service
+- Added to `npm start` script for non-systemd usage
+- Zero code changes, immediate win on every restart
+
+### 2. WebGL Addon Lazy-Loading (244KB saved on mobile, non-blocking on desktop)
+
+**Files:** `src/web/public/index.html`, `src/web/public/app.js`
+
+`xterm-addon-webgl.min.js` (244KB) was loaded eagerly for all users via `<script defer>`, but only used on desktop with WebGL2 support.
+
+- Removed `<script defer>` from `index.html`
+- Added dynamic script loading in `app.js` — only downloads on desktop when WebGL is needed
+- Mobile users never download the file at all (244KB saved)
+- Desktop: loads in parallel with page rendering, addon initializes when ready
+- Graceful fallback: canvas renderer used if WebGL unavailable or script fails
+
+### 3. Preload Hints (~50-100ms faster perceived load)
+
+**Files:** `src/web/public/index.html`
+
+Browser discovers `<script defer>` tags only when the parser reaches them at the bottom of `<body>`. By then, the HTML parse has blocked for hundreds of lines.
+
+- Added `<link rel="preload" as="script">` in `<head>` for `vendor/xterm.min.js`, `constants.js`, `app.js`
+- Browser starts fetching critical scripts immediately during HTML parse (before reaching `<body>`)
+- Zero runtime overhead — just hints for the browser's preload scanner
+
+### 4. Batch Tmux Reconciliation (N subprocess calls → 1)
+
+**Files:** `src/tmux-manager.ts`
+
+`reconcileSessions()` previously called `tmux has-session` + `tmux display-message` per known session, plus `tmux list-sessions` for discovery, plus `tmux display-message` per discovered session. With 20 sessions: 41+ subprocess calls.
+
+- Replaced with single `tmux list-panes -a -F '#{session_name}\t#{pane_pid}'` call
+- Builds a Map from the result, then does O(1) lookups for both known and discovered sessions
+- Also replaced inner O(n) `isKnown` scan with a Set lookup
+- 20 sessions: 41 subprocess calls → 1, with faster lookups
+
+### 5. Asset Hashing / Cache Busting (already implemented)
+
+**Files:** `scripts/build.mjs` (pre-existing)
+
+Content-hash cache busting was already implemented in the build script:
+- All app JS/CSS files get content hashes (`app.abc123.js`)
+- `index.html` rewritten to reference hashed filenames
+- Pre-compressed with gzip + Brotli
+- 1-year immutable cache works correctly — new deploys get new filenames
+
+## Already Optimized (No Action Needed)
+
+| Area | Why It's Fine |
+|------|---------------|
+| **SSE Broadcasting** | Single serialization per broadcast, preformatted frames, backpressure handling, session subscription filtering |
+| **State Persistence** | 500ms debounce, incremental per-session JSON caching, async atomic writes, circuit breaker on failures |
+| **Terminal Batching** | Adaptive intervals (16-50ms), per-session queues, immediate flush at 32KB, array-based accumulation |
+| **Buffer Management** | BufferAccumulator (array-push, lazy join), auto-trim at 2MB/1MB, no string concatenation in hot paths |
+| **ANSI Stripping** | Pre-compiled regex via factory functions, single-pass processing |
+| **Static File Serving** | @fastify/static with 1-year cache, pre-compressed Brotli/gzip, no-cache for HTML |
+| **Memory Management** | CleanupManager, LRUMap, StaleExpirationMap, bounded buffers, explicit listener cleanup |
+| **Import Patterns** | Pure ESM, lazy web server import, no circular deps, no dynamic imports in hot paths |
+| **Config Loading** | Small constant files, no I/O at import time, specific imports (no barrel) |

docs/archive/phase-4-domain-splitting-plan.md

@@ -0,0 +1,788 @@
+# Phase 4: Domain File Splitting — Implementation Plan
+
+**Date**: 2026-03-01
+**Prerequisites**: Phase 1-3 complete (utils cleanup, CleanupManager/Debouncer migration, route extraction)
+**Goal**: Split 4 god files into focused modules with barrel exports for transparent migration.
+
+---
+
+## Table of Contents
+
+1. [Split types.ts into types/ directory](#1-split-typests-into-types-directory)
+2. [Split ralph-tracker.ts into focused modules](#2-split-ralph-trackerts-into-focused-modules)
+3. [Split respawn-controller.ts into focused modules](#3-split-respawn-controllerts-into-focused-modules)
+4. [Split session.ts into focused modules](#4-split-sessionts-into-focused-modules)
+5. [Execution Order & Dependencies](#5-execution-order--dependencies)
+6. [Validation Checklist](#6-validation-checklist)
+
+---
+
+## 1. Split types.ts into types/ directory
+
+**Current**: 1,443 lines, 71 exports, imported by 36 files.
+**Risk**: LOW — pure type refactor, no runtime behavior change.
+
+### Target Structure
+
+```
+src/types/
+├── index.ts              (barrel re-export — transparent migration)
+├── common.ts             (Disposable, BufferConfig, CleanupResourceType, CleanupRegistration)
+├── session.ts            (SessionStatus, SessionMode, ClaudeMode, SessionConfig, SessionColor,
+│                          SessionState, OpenCodeConfig, SessionOutput)
+├── task.ts               (TaskStatus, TaskDefinition, TaskState)
+├── app-state.ts          (AppState, AppConfig, GlobalStats, TokenUsageEntry, TokenStats,
+│                          DEFAULT_CONFIG, createInitialState, createInitialGlobalStats)
+├── respawn.ts            (RespawnConfig, PersistedRespawnConfig, CycleOutcome,
+│                          RespawnCycleMetrics, RespawnAggregateMetrics, HealthStatus,
+│                          RalphLoopHealthScore, TimingHistory, RespawnPreset)
+├── ralph.ts              (RalphLoopStatus, RalphLoopState, RalphTodoStatus, RalphTodoPriority,
+│                          RalphTodoItem, RalphTodoProgress, RalphSessionState,
+│                          RalphStatusValue, RalphTestsStatus, RalphWorkType, RalphStatusBlock,
+│                          CompletionConfidence, RalphTrackerState,
+│                          CircuitBreakerState, CircuitBreakerReason, CircuitBreakerStatus,
+│                          createInitialCircuitBreakerStatus, createInitialRalphTrackerState,
+│                          createInitialRalphSessionState)
+├── api.ts                (ApiErrorCode, ApiResponse, HookEventType, QuickStartResponse,
+│                          CaseInfo, createErrorResponse, isError, getErrorMessage)
+├── lifecycle.ts          (LifecycleEventType, LifecycleEntry)
+├── run-summary.ts        (RunSummaryEventType, RunSummaryEventSeverity, RunSummaryEvent,
+│                          RunSummaryStats, RunSummary, createInitialRunSummaryStats)
+├── tools.ts              (ActiveBashToolStatus, ActiveBashTool, ImageDetectedEvent)
+├── teams.ts              (TeamConfig, TeamMember, TeamTask, InboxMessage, PaneInfo)
+├── push.ts               (PushSubscriptionRecord, VapidKeys)
+└── plan.ts               (PlanTaskStatus, TddPhase, PlanItem re-export, NiceConfig,
+                            DEFAULT_NICE_CONFIG, ProcessStats)
+```
+
+### Steps
+
+1. **Create `src/types/` directory** and each domain file above.
+
+2. **Move types** from `src/types.ts` into their domain files. Preserve all JSDoc comments. Each file should import from siblings as needed (e.g., `ralph.ts` imports `CircuitBreakerState` within itself — no cross-file deps needed since they're in the same file).
+
+3. **Create barrel `src/types/index.ts`** that re-exports everything:
+   ```typescript
+   export * from './common.js';
+   export * from './session.js';
+   export * from './task.js';
+   export * from './app-state.js';
+   export * from './respawn.js';
+   export * from './ralph.js';
+   export * from './api.js';
+   export * from './lifecycle.js';
+   export * from './run-summary.js';
+   export * from './tools.js';
+   export * from './teams.js';
+   export * from './push.js';
+   export * from './plan.js';
+   ```
+
+4. **Delete old `src/types.ts`** and replace with a single-line re-export barrel:
+   ```typescript
+   export * from './types/index.js';
+   ```
+   This ensures `import { ... } from './types.js'` continues to work everywhere — zero changes to 36 import sites.
+
+5. **Verify**: `tsc --noEmit` and `npm run lint` must pass. No runtime changes.
+
+### Internal Dependencies Between Domain Files
+
+Some types reference others across domains. Handle with imports:
+
+| File | Imports From |
+|------|-------------|
+| `app-state.ts` | `session.ts` (SessionState), `task.ts` (TaskState), `ralph.ts` (RalphLoopState, RalphSessionState) |
+| `respawn.ts` | None (self-contained) |
+| `ralph.ts` | None (self-contained) |
+| `run-summary.ts` | None (self-contained) |
+| `api.ts` | None (self-contained) |
+| `session.ts` | `respawn.ts` (RespawnConfig), `ralph.ts` (RalphTrackerState, RalphTodoItem, CircuitBreakerStatus, RalphSessionState, RunSummaryEvent) |
+
+Wait — `SessionState` references `RespawnConfig`, `RalphTrackerState`, `CircuitBreakerStatus`, and `RunSummaryEvent`. This creates imports from `session.ts` → `respawn.ts`, `ralph.ts`, `run-summary.ts`. This is fine (one-way deps, no cycles).
+
+---
+
+## 2. Split ralph-tracker.ts into focused modules
+
+**Current**: 3,868 lines, single `RalphTracker` class with 5 responsibilities.
+**Risk**: MEDIUM — class has shared mutable state, but extractable modules are well-isolated.
+
+### Coupling Analysis Summary
+
+| Module | Coupling | Extractability |
+|--------|----------|----------------|
+| Plan task tracking | LOW | HIGH — only reads `cycleCount` |
+| Fix-plan file watching | LOW | HIGH — callback-based todo replacement |
+| Iteration stall detection | LOW | HIGH — notification-based |
+| RALPH_STATUS block parsing + circuit breaker | MEDIUM | MEDIUM — callback for circuit breaker updates |
+| Todo parsing, loop detection, completion | HIGH | LOW — deeply entangled shared state |
+
+### Target Structure
+
+```
+src/
+├── ralph-tracker.ts              (~1,800 LOC — core: output parsing, loop state,
+│                                   todo management, completion detection)
+├── ralph-plan-tracker.ts         (~600 LOC — plan tasks, checkpoints, history, rollback)
+├── ralph-status-parser.ts        (~300 LOC — RALPH_STATUS block parsing, circuit breaker)
+├── ralph-fix-plan-watcher.ts     (~150 LOC — @fix_plan.md file watching)
+└── ralph-stall-detector.ts       (~80 LOC — iteration stall detection)
+```
+
+### Step 2a: Extract `RalphPlanTracker` (~600 LOC)
+
+**Why first**: Lowest coupling. Only dependency is `cycleCount` for checkpoint detection.
+
+**Extract these from `RalphTracker`**:
+
+Types to export:
+- `EnhancedPlanTask` (interface, currently lines 56-87)
+- `CheckpointReview` (interface, currently lines 90-139)
+
+Properties to move:
+- `_planVersion: number`
+- `_planHistory: Array<{version, timestamp, tasks, summary}>`
+- `_planTasks: Map<string, EnhancedPlanTask>`
+- `_checkpointIterations: number[]`
+- `_lastCheckpointIteration: number`
+
+Methods to move:
+- `initializePlanTasks(items)`
+- `updatePlanTask(taskId, update)`
+- `addPlanTask(params)`
+- `getPlanTasks()`
+- `generateCheckpointReview()`
+- `getPlanHistory()`
+- `rollbackToVersion(version)`
+- `isCheckpointDue()`
+- `planVersion` getter
+- `_savePlanToHistory()` (private)
+- `_unblockDependentTasks()` (private)
+- `_checkForCheckpoint()` (private)
+
+Events emitted (define in new class):
+- `planInitialized`
+- `planTaskUpdate`
+- `taskBlocked`
+- `taskUnblocked`
+- `planCheckpoint`
+
+**Interface with parent**:
+```typescript
+export class RalphPlanTracker extends EventEmitter {
+  constructor() { ... }
+
+  // Parent calls this when iteration changes (for checkpoint detection)
+  notifyCycleCount(cycleCount: number): void { ... }
+
+  // Full public API moves here unchanged
+  initializePlanTasks(items: PlanItem[]): void { ... }
+  updatePlanTask(taskId: string, update: { ... }): { ... } | null { ... }
+  // ...etc
+}
+```
+
+**In `RalphTracker`**: Replace plan methods with delegation:
+```typescript
+readonly planTracker = new RalphPlanTracker();
+
+// Forward plan events
+this.planTracker.on('planInitialized', (...args) => this.emit('planInitialized', ...args));
+// ...etc
+
+// In detectLoopStatus(), when cycleCount changes:
+this.planTracker.notifyCycleCount(this._loopState.cycleCount);
+```
+
+### Step 2b: Extract `RalphFixPlanWatcher` (~150 LOC)
+
+**Extract these**:
+
+Properties:
+- `_workingDir: string | null`
+- `_fixPlanPath: string | null`
+- `_fixPlanWatcher: FSWatcher | null`
+- `_fixPlanWatcherErrorHandler`
+- `_fixPlanReloadDeb`
+
+Methods:
+- `setWorkingDir(workingDir)`
+- `loadFixPlanFromDisk()`
+- `startWatchingFixPlan()`
+- `stopWatchingFixPlan()`
+- `handleFixPlanChange()`
+- `isFileAuthoritative` getter
+
+**Interface with parent**:
+```typescript
+export class RalphFixPlanWatcher extends EventEmitter {
+  get isFileAuthoritative(): boolean { ... }
+
+  setWorkingDir(workingDir: string): void { ... }
+  stop(): void { ... }
+}
+
+// Events:
+// 'todosLoaded' → (todos: Array<{id, content, status, priority}>) — parent replaces _todos
+```
+
+**In `RalphTracker`**:
+```typescript
+readonly fixPlanWatcher = new RalphFixPlanWatcher();
+
+constructor() {
+  this.fixPlanWatcher.on('todosLoaded', (items) => {
+    // Replace _todos with file-based items
+    this._todos.clear();
+    for (const item of items) {
+      this.addOrUpdateTodo(item.id, item.content, item.status, item.priority);
+    }
+  });
+}
+
+// Delegate isFileAuthoritative
+get isFileAuthoritative(): boolean {
+  return this.fixPlanWatcher.isFileAuthoritative;
+}
+```
+
+### Step 2c: Extract `RalphStallDetector` (~80 LOC)
+
+**Extract these**:
+
+Properties:
+- `_lastIterationChangeTime`
+- `_lastObservedIteration`
+- `_iterationStallTimerId`
+- `_iterationStallWarningMs`
+- `_iterationStallCriticalMs`
+- `_iterationStallWarned`
+
+Methods:
+- `startIterationStallDetection()`
+- `stopIterationStallDetection()`
+- `checkIterationStall()`
+- `getIterationStallMetrics()`
+- `configureIterationStallThresholds(warningMs, criticalMs)`
+
+**Interface with parent**:
+```typescript
+export class RalphStallDetector extends EventEmitter {
+  constructor(private cleanup: CleanupManager) { ... }
+
+  start(): void { ... }
+  stop(): void { ... }
+
+  // Parent calls when iteration changes
+  notifyIterationChanged(iteration: number): void {
+    this._lastIterationChangeTime = Date.now();
+    this._lastObservedIteration = iteration;
+    this._iterationStallWarned = false;
+  }
+
+  // Parent calls to check if loop is active
+  setLoopActive(active: boolean): void { ... }
+
+  getIterationStallMetrics(): { ... } { ... }
+}
+
+// Events: 'iterationStallWarning', 'iterationStallCritical'
+```
+
+### Step 2d: Extract `RalphStatusParser` (~300 LOC)
+
+**Extract these**:
+
+Properties:
+- `_circuitBreaker: CircuitBreakerStatus`
+- `_statusBlockBuffer: string[]`
+- `_inStatusBlock: boolean`
+- `_lastStatusBlock: RalphStatusBlock | null`
+- `_completionIndicators: number`
+- `_exitGateMet: boolean`
+- `_totalFilesModified: number`
+- `_totalTasksCompleted: number`
+
+Methods:
+- `processStatusBlockLine(line)`
+- `parseStatusBlock(lines)`
+- `detectCompletionIndicators(line)`
+- `updateCircuitBreaker(hasProgress, testsStatus, status)`
+- `resetCircuitBreaker()`
+- `circuitBreakerStatus` getter
+- `lastStatusBlock` getter
+- `cumulativeStats` getter
+- `exitGateMet` getter
+
+Regex patterns to move:
+- `RALPH_STATUS_START_PATTERN` through `RALPH_RECOMMENDATION_PATTERN`
+- `COMPLETION_INDICATOR_PATTERNS`
+
+**Interface with parent**:
+```typescript
+export class RalphStatusParser extends EventEmitter {
+  processLine(line: string): void { ... }  // calls processStatusBlockLine + detectCompletionIndicators
+
+  get circuitBreakerStatus(): CircuitBreakerStatus { ... }
+  get lastStatusBlock(): RalphStatusBlock | null { ... }
+  get exitGateMet(): boolean { ... }
+  get cumulativeStats(): { ... } { ... }
+
+  resetCircuitBreaker(): void { ... }
+  reset(): void { ... }
+}
+
+// Events: 'statusBlockDetected', 'circuitBreakerUpdate', 'exitGateMet'
+```
+
+**In `RalphTracker.processLine()`**:
+```typescript
+// Replace inline status block handling with delegation
+this.statusParser.processLine(line);
+```
+
+### Step 2e: Keep in `ralph-tracker.ts` (~1,800 LOC)
+
+The core remains tightly coupled and stays together:
+- Output parsing pipeline (`processTerminalData`, `processCleanData`, `processLine`)
+- Loop state management (`_loopState`, `detectLoopStatus`, `enable/disable/startLoop/stopLoop`)
+- Todo management (`_todos`, `detectTodoItems`, `addOrUpdateTodo`, `updateTodoStatus`, `getTodoStats`)
+- Completion detection (`detectCompletionPhrase`, `handleCompletionPhrase`, `calculateCompletionConfidence`)
+- All-tasks-complete detection (`detectAllTasksComplete`)
+- Auto-enable logic (`shouldAutoEnable`)
+- Lifecycle (`reset`, `fullReset`, `clear`, `restoreState`, `destroy`)
+- Event debouncing and buffering
+
+The class coordinates the extracted modules via composition:
+```typescript
+export class RalphTracker extends EventEmitter {
+  readonly planTracker = new RalphPlanTracker();
+  readonly fixPlanWatcher = new RalphFixPlanWatcher();
+  readonly stallDetector: RalphStallDetector;
+  readonly statusParser = new RalphStatusParser();
+
+  constructor() {
+    super();
+    this.stallDetector = new RalphStallDetector(this.cleanup);
+    this._wireSubModuleEvents();
+  }
+
+  private _wireSubModuleEvents(): void {
+    // Forward all sub-module events through RalphTracker
+    // so external consumers don't need to know about the split
+    for (const event of ['planInitialized', 'planTaskUpdate', ...]) {
+      this.planTracker.on(event, (...args) => this.emit(event, ...args));
+    }
+    // ...same for statusParser, stallDetector, fixPlanWatcher
+  }
+}
+```
+
+### Migration Safety
+
+- All events continue to be emitted from `RalphTracker` (forwarded from sub-modules)
+- All public methods stay on `RalphTracker` (delegated to sub-modules)
+- External consumers (`session.ts`, `case-routes.ts`) see zero API changes
+- New sub-modules are exposed as `readonly` properties for direct access where needed
+
+---
+
+## 3. Split respawn-controller.ts into focused modules
+
+**Current**: 3,611 lines, single `RespawnController` class with 6 responsibilities.
+**Risk**: MEDIUM — health scoring and metrics are cleanly decoupled; detection is tightly coupled.
+
+### Coupling Analysis Summary
+
+| Module | Coupling | Extractability |
+|--------|----------|----------------|
+| Health scoring | NONE | HIGH — pure calculations from metrics |
+| Cycle metrics | LOW | HIGH — standalone tracking |
+| Adaptive timing | LOW | HIGH — standalone timing adjustments |
+| Stuck-state detection | LOW | MEDIUM — needs state + config refs |
+| Pattern detection utilities | NONE | HIGH — pure functions |
+| State machine + idle detection + AI checkers | HIGH | LOW — deeply entangled |
+
+### Target Structure
+
+```
+src/
+├── respawn-controller.ts             (~2,200 LOC — state machine, idle detection,
+│                                       AI checkers, terminal handling, hook signals,
+│                                       auto-accept, step execution)
+├── respawn-health.ts                 (~250 LOC — health scoring + recommendations)
+├── respawn-metrics.ts                (~200 LOC — cycle metrics + aggregate stats)
+├── respawn-adaptive-timing.ts        (~100 LOC — adaptive timing with percentile calc)
+└── respawn-patterns.ts               (~50 LOC — terminal pattern detection utilities)
+```
+
+### Step 3a: Extract `RespawnPatterns` (~50 LOC)
+
+**Pure utility functions, zero coupling**.
+
+Move:
+- `isCompletionMessage(data): boolean`
+- `hasWorkingPattern(data, window): boolean`
+- `extractTokenCount(data): number | null`
+- `PROMPT_PATTERNS` array
+- `WORKING_PATTERNS` array
+
+```typescript
+// src/respawn-patterns.ts
+import { TOKEN_PATTERN, SPINNER_PATTERN } from './utils/index.js';
+
+export const PROMPT_PATTERNS = ['❯', '>', '$', '%', '#'];
+
+export const WORKING_PATTERNS = [/* 70+ patterns */];
+
+export function isCompletionMessage(data: string): boolean { ... }
+export function hasWorkingPattern(data: string, window: string): boolean { ... }
+export function extractTokenCount(data: string): number | null { ... }
+```
+
+**In `RespawnController`**: Import and call:
+```typescript
+import { isCompletionMessage, hasWorkingPattern, extractTokenCount } from './respawn-patterns.js';
+```
+
+### Step 3b: Extract `RespawnAdaptiveTiming` (~100 LOC)
+
+**Self-contained timing controller**.
+
+Move properties:
+- `timingHistory: TimingHistory`
+
+Move methods:
+- `recordTimingData(idleDetectionMs, cycleDurationMs)`
+- `updateAdaptiveTiming()`
+- `getTimingHistory()`
+- `getAdaptiveCompletionConfirmMs()`
+
+```typescript
+export class RespawnAdaptiveTiming {
+  private timingHistory: TimingHistory;
+
+  constructor(private config: { adaptiveMinConfirmMs: number; adaptiveMaxConfirmMs: number }) {
+    this.timingHistory = { recentIdleDetectionMs: [], recentCycleDurationMs: [], ... };
+  }
+
+  recordTimingData(idleDetectionMs: number, cycleDurationMs: number): void { ... }
+  getAdaptiveCompletionConfirmMs(): number { ... }
+  getTimingHistory(): TimingHistory { ... }
+  reset(): void { ... }
+}
+```
+
+### Step 3c: Extract `RespawnCycleMetrics` (~200 LOC)
+
+**Standalone metrics tracker**.
+
+Move properties:
+- `currentCycleMetrics`
+- `recentCycleMetrics[]`
+- `aggregateMetrics`
+- `MAX_CYCLE_METRICS_IN_MEMORY`
+
+Move methods:
+- `startCycleMetrics(idleReason)`
+- `recordCycleStep(step)`
+- `completeCycleMetrics(outcome, errorMessage?)`
+- `updateAggregateMetrics(metrics)`
+- `getAggregateMetrics()`
+- `getRecentCycleMetrics(limit?)`
+
+```typescript
+export class RespawnCycleMetricsTracker {
+  private currentCycleMetrics: Partial<RespawnCycleMetrics> | null = null;
+  private recentCycleMetrics: RespawnCycleMetrics[] = [];
+  private aggregateMetrics: RespawnAggregateMetrics;
+
+  startCycle(sessionId: string, cycleNumber: number, idleReason: string): void { ... }
+  recordStep(step: string): void { ... }
+  completeCycle(outcome: CycleOutcome, errorMessage?: string): RespawnCycleMetrics | null { ... }
+  getAggregate(): RespawnAggregateMetrics { ... }
+  getRecent(limit?: number): RespawnCycleMetrics[] { ... }
+  reset(): void { ... }
+}
+```
+
+**Callback**: `completeCycle()` returns the completed metrics so the controller can pass them to `adaptiveTiming.recordTimingData()`.
+
+### Step 3d: Extract `RespawnHealthCalculator` (~250 LOC)
+
+**Pure calculation — no state of its own**.
+
+Move methods:
+- `calculateHealthScore()`
+- `calculateCycleSuccessScore()`
+- `calculateCircuitBreakerScore()`
+- `calculateIterationProgressScore()`
+- `calculateAiCheckerScore()`
+- `calculateStuckRecoveryScore()`
+- `generateHealthRecommendations(components)`
+- `generateHealthSummary(score, status, components)`
+- `shouldSkipClear()` (belongs here since it's a pure calculation on token/config)
+
+```typescript
+export interface HealthInputs {
+  aggregateMetrics: RespawnAggregateMetrics;
+  circuitBreakerStatus: CircuitBreakerStatus;
+  iterationStallMetrics: { stallDurationMs: number; warningMs: number; criticalMs: number } | null;
+  aiCheckerState: { disabled: boolean; inCooldown: boolean; hasErrors: boolean };
+  stuckRecoveryCount: number;
+  maxStuckRecoveries: number;
+}
+
+export function calculateHealthScore(inputs: HealthInputs): RalphLoopHealthScore { ... }
+
+export function shouldSkipClear(
+  lastTokenCount: number,
+  skipClearThresholdPercent: number,
+  maxContextTokens: number
+): boolean { ... }
+```
+
+**Made as pure functions** (not a class) since they hold no state.
+
+### Step 3e: Keep in `respawn-controller.ts` (~2,200 LOC)
+
+The core state machine, idle detection, and AI checker integration stays:
+- State machine transitions (`setState`, `start`, `stop`, `pause`, `resume`)
+- Terminal data handling (`handleTerminalData`)
+- All 5 idle detection layers + hook signals
+- AI checker integration (`tryStartAiCheck`, `startAiCheck`, `startPlanCheck`)
+- Auto-accept logic
+- Step execution (`sendUpdateDocs`, `sendClear`, `sendInit`, `sendKickstart`)
+- Timer management (`startTrackedTimer`, `cancelTrackedTimer`)
+- Stuck-state detection and recovery
+- Action logging
+
+The class composes extracted modules:
+```typescript
+import { RespawnAdaptiveTiming } from './respawn-adaptive-timing.js';
+import { RespawnCycleMetricsTracker } from './respawn-metrics.js';
+import { calculateHealthScore, shouldSkipClear } from './respawn-health.js';
+import { isCompletionMessage, hasWorkingPattern, extractTokenCount } from './respawn-patterns.js';
+
+export class RespawnController extends EventEmitter {
+  private adaptiveTiming: RespawnAdaptiveTiming;
+  private cycleMetrics: RespawnCycleMetricsTracker;
+
+  calculateHealthScore(): RalphLoopHealthScore {
+    return calculateHealthScore({
+      aggregateMetrics: this.cycleMetrics.getAggregate(),
+      circuitBreakerStatus: this.session.ralphTracker.circuitBreakerStatus,
+      iterationStallMetrics: this.session.ralphTracker.getIterationStallMetrics(),
+      aiCheckerState: { ... },
+      stuckRecoveryCount: this.stuckRecoveryCount,
+      maxStuckRecoveries: this.config.maxStuckRecoveries ?? 3,
+    });
+  }
+}
+```
+
+---
+
+## 4. Split session.ts into focused modules
+
+**Current**: 2,418 lines, single `Session` class.
+**Risk**: LOW-MEDIUM — extractable pieces are utility-like with clear boundaries.
+
+### Coupling Analysis Summary
+
+| Module | Coupling | Extractability |
+|--------|----------|----------------|
+| CLI arg builder | NONE | HIGH — pure functions used at spawn time |
+| Auto-compact/clear | LOW | HIGH — self-contained automation with config |
+| Token tracking | LOW | MEDIUM — reads PTY output, writes state |
+| Task description cache | LOW | HIGH — separate LRU cache |
+| PTY + mux lifecycle | HIGH | KEEP — core of the class |
+| Tracker integration | HIGH | KEEP — event forwarding plumbing |
+
+### Target Structure
+
+```
+src/
+├── session.ts                    (~1,600 LOC — PTY lifecycle, terminal I/O,
+│                                   tracker integration, output processing,
+│                                   token tracking, state management)
+├── session-cli-builder.ts        (~250 LOC — Claude/OpenCode CLI arg construction)
+├── session-auto-ops.ts           (~300 LOC — auto-compact, auto-clear automation)
+└── session-task-cache.ts         (~100 LOC — task description LRU cache)
+```
+
+### Step 4a: Extract `SessionCliBuilder` (~250 LOC)
+
+**Pure functions — zero coupling to Session instance**.
+
+Move:
+- `buildClaudeArgs()` logic (currently inlined in `startInteractive` and `runPrompt`)
+- `buildOpenCodeArgs()` logic
+- Model mapping constants
+- Claude mode to flag mapping
+- Environment variable construction
+
+```typescript
+// src/session-cli-builder.ts
+export interface CliBuilderConfig {
+  claudeMode: ClaudeMode;
+  model?: string;
+  workingDir: string;
+  sessionId: string;
+  niceConfig?: NiceConfig;
+  isOpenCode?: boolean;
+  openCodeConfig?: OpenCodeConfig;
+}
+
+export function buildInteractiveArgs(config: CliBuilderConfig): string[] { ... }
+export function buildPromptArgs(config: CliBuilderConfig, prompt: string): string[] { ... }
+export function buildShellArgs(shell?: string): string[] { ... }
+export function buildClaudeEnv(config: CliBuilderConfig): Record<string, string> { ... }
+```
+
+### Step 4b: Extract `SessionAutoOps` (~300 LOC)
+
+**Self-contained automation with config-based thresholds**.
+
+Move properties:
+- `_autoCompactThreshold`
+- `_autoClearThreshold`
+- `_isAutoCompacting`
+- `_isAutoClearing`
+- `_autoCompactCount`
+- `_autoClearCount`
+- `_lastAutoCompactTime`
+- `_lastAutoClearTime`
+
+Move methods:
+- `checkAutoCompact(tokenCount)`
+- `performAutoCompact()`
+- `checkAutoClear(tokenCount)`
+- `performAutoClear()`
+- Auto-compact/clear threshold configuration
+
+```typescript
+export class SessionAutoOps extends EventEmitter {
+  constructor(
+    private writeCommand: (command: string) => Promise<void>,
+    private getTokenCount: () => number,
+    config: { compactThreshold: number; clearThreshold: number }
+  ) { ... }
+
+  /** Called after token count updates. Checks thresholds and triggers if needed. */
+  checkThresholds(tokenCount: number): void { ... }
+
+  updateConfig(config: { compactThreshold?: number; clearThreshold?: number }): void { ... }
+  getStats(): { autoCompactCount: number; autoClearCount: number; ... } { ... }
+}
+
+// Events: 'autoCompact', 'autoClear'
+```
+
+**In `Session`**: Compose and wire:
+```typescript
+private autoOps = new SessionAutoOps(
+  (cmd) => this.writeViaMux(cmd),
+  () => this._state.tokenCount,
+  { compactThreshold: 110_000, clearThreshold: 140_000 }
+);
+```
+
+### Step 4c: Extract `SessionTaskCache` (~100 LOC)
+
+**Isolated LRU cache for task descriptions**.
+
+Move:
+- `_taskDescriptionCache: LRUMap<number, { description: string; timestamp: number }>`
+- `_taskDescriptionMaxAge`
+- `findTaskDescriptionNear(lineNumber)`
+- `cacheTaskDescription(lineNumber, description)`
+
+```typescript
+export class SessionTaskCache {
+  private cache: LRUMap<number, { description: string; timestamp: number }>;
+  private maxAgeMs: number;
+
+  constructor(maxSize: number = 50, maxAgeMs: number = 30_000) { ... }
+
+  find(lineNumber: number, searchRadius: number = 50): string | null { ... }
+  add(lineNumber: number, description: string): void { ... }
+  clear(): void { ... }
+}
+```
+
+### Step 4d: Keep in `session.ts` (~1,600 LOC)
+
+The core stays together:
+- PTY process management (`spawn`, `kill`, `resize`, `writeViaMux`)
+- Data streaming pipeline (PTY → buffer → ANSI strip → JSON parse → events)
+- Tracker initialization and event forwarding (RalphTracker, BashToolParser, TaskTracker)
+- Output processing (message extraction, completion detection)
+- Token tracking (status line parsing)
+- State management (`toState()`, `updateState()`)
+- Session lifecycle (`startInteractive`, `startShell`, `runPrompt`)
+- CLI info detection (version, model, account)
+
+---
+
+## 5. Execution Order & Dependencies
+
+Execute in this order to minimize risk. Each step is independently deployable.
+
+```
+Step 1: types.ts split
+  ↓  (no runtime change, just file reorganization)
+Step 2a: RalphPlanTracker extraction
+  ↓  (independent of types split)
+Step 2b: RalphFixPlanWatcher extraction
+Step 2c: RalphStallDetector extraction
+Step 2d: RalphStatusParser extraction
+  ↓  (ralph-tracker.ts now ~1,800 LOC)
+Step 3a: RespawnPatterns extraction
+Step 3b: RespawnAdaptiveTiming extraction
+Step 3c: RespawnCycleMetrics extraction
+Step 3d: RespawnHealthCalculator extraction
+  ↓  (respawn-controller.ts now ~2,200 LOC)
+Step 4a: SessionCliBuilder extraction
+Step 4b: SessionAutoOps extraction
+Step 4c: SessionTaskCache extraction
+  ↓  (session.ts now ~1,600 LOC)
+```
+
+**Parallelization**: Steps 1, 2a-2d, 3a-3d, and 4a-4c can be done by separate agents in parallel since they touch different files. However, within each group, sequential execution is safer.
+
+### Risk Mitigation
+
+- **Barrel exports**: Every split uses delegation + barrel re-export so external consumers see zero API changes
+- **Event forwarding**: Sub-modules emit events, parent class forwards them — no event contract changes
+- **Incremental**: Each step can be verified independently with `tsc --noEmit` + `npm run lint`
+- **No test changes needed**: External API stays identical; existing tests continue to pass
+
+---
+
+## 6. Validation Checklist
+
+After each step, verify:
+
+- [ ] `tsc --noEmit` passes (no type errors)
+- [ ] `npm run lint` passes (no unused imports, etc.)
+- [ ] `npm run format:check` passes
+- [ ] `npx vitest run test/respawn-controller.test.ts` passes (for respawn splits)
+- [ ] `npx vitest run test/ralph-tracker.test.ts` passes (for ralph splits)
+- [ ] `npx vitest run test/session-manager.test.ts` passes (for session splits)
+- [ ] Dev server starts: `npx tsx src/index.ts web`
+- [ ] Existing sessions work (create, interact, delete)
+- [ ] Respawn cycle works (enable respawn, verify idle detection fires)
+- [ ] No new circular dependencies: `npx madge --circular src/`
+
+### Size Targets
+
+| File | Before | After |
+|------|--------|-------|
+| `src/types.ts` | 1,443 LOC | 1 LOC (re-export barrel) |
+| `src/ralph-tracker.ts` | 3,868 LOC | ~1,800 LOC |
+| `src/respawn-controller.ts` | 3,611 LOC | ~2,200 LOC |
+| `src/session.ts` | 2,418 LOC | ~1,600 LOC |
+| **Total new files** | — | 12 files |
+| **Net LOC change** | — | ~0 (refactor only) |

docs/archive/phase1-implementation-plan.md

@@ -0,0 +1,738 @@
+# Phase 1 Implementation Plan: Quick Wins
+
+**Source**: `docs/code-structure-findings.md` (Phase 1 - Quick Wins section)
+**Estimated effort**: 1-2 days
+**Tasks**: 5 independent tasks (can be done in parallel unless noted)
+
+---
+
+## Safety Constraints
+
+Before starting ANY work, read and follow these rules:
+
+1. **Never run `npx vitest run`** (full suite) -- it kills tmux sessions. You are running inside a Codeman-managed tmux session.
+2. **Run individual tests only**: `npx vitest run test/<file>.test.ts`
+3. **Never test on port 3000** -- the live dev server runs there. Tests use ports 3150+.
+4. **After TypeScript changes**: Run `tsc --noEmit` to verify type checking passes.
+5. **Before considering done**: Run `npm run lint` and `npm run format:check` to ensure CI passes.
+6. **Never kill tmux sessions** -- check `echo $CODEMAN_MUX` first.
+
+---
+
+## Task Dependencies
+
+All 5 tasks are independent and can be done in parallel. However:
+- Task 1 (barrel exports) is a prerequisite if you want to update import sites to use the barrel after Task 3 (consolidate EXEC_TIMEOUT_MS). The EXEC_TIMEOUT_MS consolidation creates a new export that should be added to the barrel.
+- Task 2 (delete dead functions) removes functions that Task 1 would otherwise need to add to the barrel. Do Task 2 first or simultaneously with Task 1 to avoid adding exports for dead code.
+
+**Recommended order**: Task 2 -> Task 1 -> Task 3 -> Task 4 -> Task 5
+
+---
+
+## Task 1: Export Missing Functions from Utils Barrel
+
+**File**: `src/utils/index.ts`
+**Time**: ~30 minutes
+
+### Problem
+
+The barrel file (`src/utils/index.ts`) is missing exports for several functions that are defined in util modules, forcing consumers to use deep imports or preventing usage entirely.
+
+### Missing Exports
+
+From `src/utils/regex-patterns.ts`:
+- `createAnsiPatternFull()` -- factory for fresh ANSI regex (documented in CLAUDE.md)
+- `createAnsiPatternSimple()` -- factory for fresh ANSI regex (documented in CLAUDE.md)
+- `stripAnsi()` -- ANSI stripping utility
+- `SAFE_PATH_PATTERN` -- regex for safe file paths (currently deep-imported by `schemas.ts` and `tmux-manager.ts`)
+
+From `src/utils/token-validation.ts`:
+- `validateTokenCounts()` -- token count validation (documented in CLAUDE.md)
+- `validateTokensAndCost()` -- token + cost validation (documented in CLAUDE.md)
+
+**Note**: Do NOT export `isSimilar`, `isSimilarByDistance`, `levenshteinDistance`, or `normalizePhrase` from `string-similarity.ts` -- these are dead code (see Task 2).
+
+### Edit 1: Add missing regex-patterns exports
+
+**File**: `src/utils/index.ts`
+
+**Old code** (lines 13-18):
+```typescript
+export {
+  ANSI_ESCAPE_PATTERN_FULL,
+  ANSI_ESCAPE_PATTERN_SIMPLE,
+  TOKEN_PATTERN,
+  SPINNER_PATTERN,
+} from './regex-patterns.js';
+```
+
+**New code**:
+```typescript
+export {
+  ANSI_ESCAPE_PATTERN_FULL,
+  ANSI_ESCAPE_PATTERN_SIMPLE,
+  TOKEN_PATTERN,
+  SPINNER_PATTERN,
+  createAnsiPatternFull,
+  createAnsiPatternSimple,
+  stripAnsi,
+  SAFE_PATH_PATTERN,
+} from './regex-patterns.js';
+```
+
+### Edit 2: Add missing token-validation exports
+
+**File**: `src/utils/index.ts`
+
+**Old code** (line 19):
+```typescript
+export { MAX_SESSION_TOKENS } from './token-validation.js';
+```
+
+**New code**:
+```typescript
+export { MAX_SESSION_TOKENS, validateTokenCounts, validateTokensAndCost } from './token-validation.js';
+```
+
+### Optional follow-up: Update deep imports to use barrel
+
+These files currently deep-import `SAFE_PATH_PATTERN` and could be updated to use the barrel instead:
+
+- `src/web/schemas.ts` line 11: `import { SAFE_PATH_PATTERN } from '../utils/regex-patterns.js';` could become `import { SAFE_PATH_PATTERN } from '../utils/index.js';`
+- `src/tmux-manager.ts` line 44: `import { SAFE_PATH_PATTERN } from './utils/regex-patterns.js';` could become part of existing barrel import
+
+This is a low-priority cosmetic change. The barrel export itself is the important fix.
+
+### Verification
+
+```bash
+tsc --noEmit
+npm run lint
+```
+
+---
+
+## Task 2: Delete Dead Utility Functions
+
+**File**: `src/utils/string-similarity.ts`
+**Time**: ~15 minutes
+
+### Problem
+
+Four exported functions in `string-similarity.ts` are never imported anywhere in the codebase:
+- `levenshteinDistance()` (lines 27-69)
+- `isSimilar()` (lines 106-108)
+- `isSimilarByDistance()` (lines 123-125)
+- `normalizePhrase()` (lines 139-144)
+
+Only three functions are actually used (all by `ralph-tracker.ts` via the barrel):
+- `stringSimilarity()` -- uses `levenshteinDistance()` internally
+- `fuzzyPhraseMatch()` -- uses `normalizePhrase()` and `isSimilarByDistance()` internally
+- `todoContentHash()`
+
+### Strategy
+
+`levenshteinDistance()` is called by `stringSimilarity()`, and `normalizePhrase()` and `isSimilarByDistance()` are called by `fuzzyPhraseMatch()`. So they cannot be deleted -- they just need to be un-exported (made private to the module).
+
+`isSimilar()` is truly dead -- not called by anything. Delete it entirely.
+
+### Edit 1: Remove `export` from `levenshteinDistance`
+
+**File**: `src/utils/string-similarity.ts`
+
+**Old code** (line 27):
+```typescript
+export function levenshteinDistance(a: string, b: string): number {
+```
+
+**New code**:
+```typescript
+function levenshteinDistance(a: string, b: string): number {
+```
+
+### Edit 2: Delete `isSimilar` function entirely
+
+**File**: `src/utils/string-similarity.ts`
+
+**Old code** (lines 94-108):
+```typescript
+/**
+ * Check if two strings are similar within a given threshold.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param threshold - Minimum similarity ratio (default: 0.85 = 85% similar)
+ * @returns True if similarity >= threshold
+ *
+ * @example
+ * isSimilar('COMPLETE', 'COMPLET', 0.85)  // true (87.5% similar)
+ * isSimilar('COMPLETE', 'DONE', 0.85)     // false (0% similar)
+ */
+export function isSimilar(a: string, b: string, threshold = 0.85): boolean {
+  return stringSimilarity(a, b) >= threshold;
+}
+```
+
+**New code**: (delete entirely -- replace with empty string)
+
+### Edit 3: Remove `export` from `isSimilarByDistance`
+
+**File**: `src/utils/string-similarity.ts`
+
+**Old code** (line 123):
+```typescript
+export function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
+```
+
+**New code**:
+```typescript
+function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
+```
+
+### Edit 4: Remove `export` from `normalizePhrase`
+
+**File**: `src/utils/string-similarity.ts`
+
+**Old code** (line 139):
+```typescript
+export function normalizePhrase(phrase: string): string {
+```
+
+**New code**:
+```typescript
+function normalizePhrase(phrase: string): string {
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+npx vitest run test/string-utilities.test.ts
+npm run lint
+```
+
+Note: If `test/string-utilities.test.ts` imports any of the now-unexported functions, those test imports will fail. Check the test file and remove tests for `isSimilar` (deleted) and update any direct tests for `levenshteinDistance`, `isSimilarByDistance`, `normalizePhrase` to test them indirectly through the public API (`stringSimilarity`, `fuzzyPhraseMatch`), or remove those tests.
+
+---
+
+## Task 3: Consolidate Duplicated `EXEC_TIMEOUT_MS` Constant
+
+**Files**:
+- `src/utils/claude-cli-resolver.ts` (line 17)
+- `src/utils/opencode-cli-resolver.ts` (line 16)
+- `src/tmux-manager.ts` (line 63) -- also has its own copy
+
+**Time**: ~15 minutes
+
+### Problem
+
+`EXEC_TIMEOUT_MS = 5000` is defined identically in three files. Changes need to happen in all three places.
+
+### Strategy
+
+Create a shared constant and export it. The natural home is a new config file since the existing config files (`buffer-limits.ts`, `map-limits.ts`) follow this pattern. However, to keep it minimal, we can add it to an existing config file or create a small one.
+
+**Recommended approach**: Add to `src/config/timing-config.ts` (new file) as a single constant. This file can grow later in Phase 6 to hold other timing constants.
+
+Alternatively, the simplest approach: export from one of the existing utils and import in the others. Since both CLI resolvers are in `src/utils/`, the cleanest approach is to put it in a shared location.
+
+### Option A: Add to existing config (simpler)
+
+Create `src/config/exec-timeout.ts`:
+
+**New file**: `src/config/exec-timeout.ts`
+```typescript
+/**
+ * Timeout for child process exec commands (e.g., `which claude`, `which opencode`, tmux commands).
+ * Used across CLI resolvers and tmux manager.
+ */
+export const EXEC_TIMEOUT_MS = 5000;
+```
+
+### Edit 1: Update `claude-cli-resolver.ts`
+
+**File**: `src/utils/claude-cli-resolver.ts`
+
+**Old code** (lines 11-17):
+```typescript
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Timeout for exec commands (5 seconds) */
+const EXEC_TIMEOUT_MS = 5000;
+```
+
+**New code**:
+```typescript
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+```
+
+### Edit 2: Update `opencode-cli-resolver.ts`
+
+**File**: `src/utils/opencode-cli-resolver.ts`
+
+**Old code** (lines 10-16):
+```typescript
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Timeout for exec commands (5 seconds) */
+const EXEC_TIMEOUT_MS = 5000;
+```
+
+**New code**:
+```typescript
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+```
+
+### Edit 3: Update `tmux-manager.ts`
+
+**File**: `src/tmux-manager.ts`
+
+**Old code** (line 63):
+```typescript
+const EXEC_TIMEOUT_MS = 5000;
+```
+
+**New code**:
+```typescript
+import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
+```
+
+Note: `tmux-manager.ts` already has many imports at the top of the file. Add this import near the other local imports (around lines 43-56). The `const EXEC_TIMEOUT_MS = 5000;` on line 63 should be deleted entirely (replaced with the import).
+
+### Verification
+
+```bash
+tsc --noEmit
+npm run lint
+```
+
+---
+
+## Task 4: Add `z.infer` to Zod Schemas
+
+**Files**:
+- `src/web/schemas.ts` (add type exports)
+- `src/types.ts` (replace manual interfaces with `z.infer` re-exports where applicable)
+
+**Time**: ~2 hours
+
+### Problem
+
+All 30+ Zod schemas in `schemas.ts` define validation rules, but zero use `z.infer` to derive TypeScript types. Instead, `types.ts` manually duplicates interfaces that match the schemas. When a schema changes, the type must be manually updated too.
+
+### Strategy
+
+Add `z.infer` type exports to `schemas.ts` for each exported schema. This creates derived types as the single source of truth. For schemas that have corresponding manual interfaces in `types.ts`, the manual interface can be replaced with a re-export of the inferred type.
+
+**Important**: Not all schemas have matching interfaces in `types.ts`. The `RespawnConfig` interface in `types.ts` (line 395) has all required fields, while `RespawnConfigSchema` has all optional fields (it's for partial updates). These are NOT the same type and should NOT be unified.
+
+### Edit 1: Add inferred type exports to `schemas.ts`
+
+**File**: `src/web/schemas.ts`
+
+After each schema definition, add a corresponding type export. Add the following lines at the **end of the file** (after line 509):
+
+**Old code** (end of file, lines 506-509):
+```typescript
+    .optional(),
+});
+```
+
+Wait -- the end of file is actually at line 509 after the `RalphLoopStartSchema`. Add the type exports after the last schema:
+
+**Append to end of file** `src/web/schemas.ts`:
+
+```typescript
+
+// ========== Inferred Types ==========
+// Derive TypeScript types from Zod schemas (single source of truth)
+
+export type CreateSessionInput = z.infer<typeof CreateSessionSchema>;
+export type RunPromptInput = z.infer<typeof RunPromptSchema>;
+export type ResizeInput = z.infer<typeof ResizeSchema>;
+export type CreateCaseInput = z.infer<typeof CreateCaseSchema>;
+export type QuickStartInput = z.infer<typeof QuickStartSchema>;
+export type HookEventInput = z.infer<typeof HookEventSchema>;
+export type RespawnConfigInput = z.infer<typeof RespawnConfigSchema>;
+export type ConfigUpdateInput = z.infer<typeof ConfigUpdateSchema>;
+export type SettingsUpdateInput = z.infer<typeof SettingsUpdateSchema>;
+export type SessionInputWithLimitInput = z.infer<typeof SessionInputWithLimitSchema>;
+export type SessionNameInput = z.infer<typeof SessionNameSchema>;
+export type SessionColorInput = z.infer<typeof SessionColorSchema>;
+export type RalphConfigInput = z.infer<typeof RalphConfigSchema>;
+export type FixPlanImportInput = z.infer<typeof FixPlanImportSchema>;
+export type RalphPromptWriteInput = z.infer<typeof RalphPromptWriteSchema>;
+export type AutoClearInput = z.infer<typeof AutoClearSchema>;
+export type AutoCompactInput = z.infer<typeof AutoCompactSchema>;
+export type ImageWatcherInput = z.infer<typeof ImageWatcherSchema>;
+export type FlickerFilterInput = z.infer<typeof FlickerFilterSchema>;
+export type QuickRunInput = z.infer<typeof QuickRunSchema>;
+export type ScheduledRunInput = z.infer<typeof ScheduledRunSchema>;
+export type LinkCaseInput = z.infer<typeof LinkCaseSchema>;
+export type GeneratePlanInput = z.infer<typeof GeneratePlanSchema>;
+export type GeneratePlanDetailedInput = z.infer<typeof GeneratePlanDetailedSchema>;
+export type CancelPlanInput = z.infer<typeof CancelPlanSchema>;
+export type PlanTaskUpdateInput = z.infer<typeof PlanTaskUpdateSchema>;
+export type PlanTaskAddInput = z.infer<typeof PlanTaskAddSchema>;
+export type CpuLimitInput = z.infer<typeof CpuLimitSchema>;
+export type SubagentWindowStatesInput = z.infer<typeof SubagentWindowStatesSchema>;
+export type SubagentParentMapInput = z.infer<typeof SubagentParentMapSchema>;
+export type InteractiveRespawnInput = z.infer<typeof InteractiveRespawnSchema>;
+export type RespawnEnableInput = z.infer<typeof RespawnEnableSchema>;
+export type PushSubscribeInput = z.infer<typeof PushSubscribeSchema>;
+export type PushPreferencesUpdateInput = z.infer<typeof PushPreferencesUpdateSchema>;
+export type RalphLoopStartInput = z.infer<typeof RalphLoopStartSchema>;
+```
+
+### What NOT to do
+
+Do NOT replace the `RespawnConfig` interface in `types.ts` with `z.infer<typeof RespawnConfigSchema>`. The schema has all optional fields (for partial config updates), but the interface has required fields (for the full config object). These are intentionally different shapes.
+
+Similarly, do NOT try to unify every interface in `types.ts` with a schema -- most interfaces in `types.ts` represent internal domain objects (SessionState, TaskState, etc.) that have no corresponding Zod schema. The schemas only exist for API request validation.
+
+### Future opportunity
+
+In a future phase, route handlers in `server.ts` can use these inferred types for request body typing:
+```typescript
+const body = CreateSessionSchema.parse(request.body) as CreateSessionInput;
+```
+This task only adds the type exports. Migrating route handlers to use them is out of scope.
+
+### Verification
+
+```bash
+tsc --noEmit
+npm run lint
+npm run format:check
+```
+
+---
+
+## Task 5: Fix Weak `not.toThrow()` Tests with Behavioral Assertions
+
+**Files**:
+- `test/task-tracker.test.ts` -- 6 instances
+- `test/image-watcher.test.ts` -- 1 instance
+- `test/task-queue.test.ts` -- 1 instance
+- `test/hooks-config.test.ts` -- 1 instance
+- `test/session-manager.test.ts` -- 1 instance
+
+**Time**: ~1 hour
+
+### Problem
+
+10 tests only assert `not.toThrow()` without verifying the actual defensive behavior. These tests prove the code doesn't crash but don't verify it does the right thing.
+
+### Fix Strategy
+
+After each `not.toThrow()`, add a behavioral assertion that verifies the state is correct (e.g., no tasks were created, no side effects occurred).
+
+### Edit 1: `task-tracker.test.ts` -- null message (line 566)
+
+**File**: `test/task-tracker.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle null message', () => {
+      expect(() => tracker.processMessage(null)).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle null message', () => {
+      expect(() => tracker.processMessage(null)).not.toThrow();
+      expect(tracker.getAllTasks().size).toBe(0);
+      expect(tracker.getRunningCount()).toBe(0);
+    });
+```
+
+### Edit 2: `task-tracker.test.ts` -- message without content (line 569-571)
+
+**File**: `test/task-tracker.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle message without content', () => {
+      expect(() => tracker.processMessage({ message: {} })).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle message without content', () => {
+      expect(() => tracker.processMessage({ message: {} })).not.toThrow();
+      expect(tracker.getAllTasks().size).toBe(0);
+    });
+```
+
+### Edit 3: `task-tracker.test.ts` -- empty content array (line 573-575)
+
+**File**: `test/task-tracker.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle empty content array', () => {
+      expect(() => tracker.processMessage({ message: { content: [] } })).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle empty content array', () => {
+      expect(() => tracker.processMessage({ message: { content: [] } })).not.toThrow();
+      expect(tracker.getAllTasks().size).toBe(0);
+    });
+```
+
+### Edit 4: `task-tracker.test.ts` -- tool_result for unknown task (lines 577-590)
+
+**File**: `test/task-tracker.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle tool_result for unknown task', () => {
+      expect(() => {
+        tracker.processMessage({
+          message: {
+            content: [{
+              type: 'tool_result',
+              tool_use_id: 'unknown-task',
+              is_error: false,
+              content: 'Done',
+            }],
+          },
+        });
+      }).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle tool_result for unknown task', () => {
+      expect(() => {
+        tracker.processMessage({
+          message: {
+            content: [{
+              type: 'tool_result',
+              tool_use_id: 'unknown-task',
+              is_error: false,
+              content: 'Done',
+            }],
+          },
+        });
+      }).not.toThrow();
+      expect(tracker.getTask('unknown-task')).toBeUndefined();
+      expect(tracker.getAllTasks().size).toBe(0);
+    });
+```
+
+### Edit 5: `task-tracker.test.ts` -- empty terminal output (lines 592-595)
+
+**File**: `test/task-tracker.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle empty terminal output', () => {
+      expect(() => tracker.processTerminalOutput('')).not.toThrow();
+      expect(() => tracker.processTerminalOutput('   ')).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle empty terminal output', () => {
+      expect(() => tracker.processTerminalOutput('')).not.toThrow();
+      expect(() => tracker.processTerminalOutput('   ')).not.toThrow();
+      expect(tracker.getAllTasks().size).toBe(0);
+      expect(tracker.getRunningCount()).toBe(0);
+    });
+```
+
+### Edit 6: `image-watcher.test.ts` -- unwatchSession for non-watched session (line 123)
+
+**File**: `test/image-watcher.test.ts`
+
+**Old code**:
+```typescript
+    it('should be safe to call for non-watched session', () => {
+      expect(() => watcher.unwatchSession('nonexistent')).not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should be safe to call for non-watched session', () => {
+      expect(() => watcher.unwatchSession('nonexistent')).not.toThrow();
+      expect(watcher.getWatchedSessions()).toHaveLength(0);
+    });
+```
+
+### Edit 7: `task-queue.test.ts` -- dependencies on non-existent tasks (lines 538-542)
+
+**File**: `test/task-queue.test.ts`
+
+**Old code**:
+```typescript
+  it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
+    // Dependencies on non-existent tasks are valid - they just won't be satisfied
+    expect(() => {
+      queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
+    }).not.toThrow();
+  });
+```
+
+**New code**:
+```typescript
+  it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
+    // Dependencies on non-existent tasks are valid - they just won't be satisfied
+    let task: ReturnType<typeof queue.addTask> | undefined;
+    expect(() => {
+      task = queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
+    }).not.toThrow();
+    expect(task).toBeDefined();
+    expect(task!.dependencies).toEqual(['non-existent-id']);
+    // Task should be pending but blocked (dependency unsatisfied)
+    expect(queue.next()?.prompt).toBeUndefined();
+  });
+```
+
+Wait -- `queue.next()` returns `null` when no next task is available (all blocked). Let me adjust:
+
+**New code** (corrected):
+```typescript
+  it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
+    // Dependencies on non-existent tasks are valid - they just won't be satisfied
+    let task: ReturnType<typeof queue.addTask> | undefined;
+    expect(() => {
+      task = queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
+    }).not.toThrow();
+    expect(task).toBeDefined();
+    expect(task!.dependencies).toEqual(['non-existent-id']);
+    // Task exists but is blocked (dependency unsatisfied), so next() skips it
+    expect(queue.getAllTasks()).toHaveLength(1);
+    expect(queue.next()).toBeNull();
+  });
+```
+
+### Edit 8: `hooks-config.test.ts` -- valid JSON check (line 129)
+
+**File**: `test/hooks-config.test.ts`
+
+**Old code**:
+```typescript
+  it('should write valid JSON', () => {
+    writeHooksConfig(testDir);
+    const settingsPath = join(testDir, '.claude', 'settings.local.json');
+    const content = readFileSync(settingsPath, 'utf-8');
+    expect(() => JSON.parse(content)).not.toThrow();
+  });
+```
+
+**New code**:
+```typescript
+  it('should write valid JSON', () => {
+    writeHooksConfig(testDir);
+    const settingsPath = join(testDir, '.claude', 'settings.local.json');
+    const content = readFileSync(settingsPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    expect(parsed).toBeDefined();
+    expect(typeof parsed).toBe('object');
+    expect(parsed.hooks).toBeDefined();
+  });
+```
+
+### Edit 9: `session-manager.test.ts` -- stopSession for non-existent (line 216)
+
+**File**: `test/session-manager.test.ts`
+
+**Old code**:
+```typescript
+    it('should handle non-existent session gracefully', async () => {
+      await expect(manager.stopSession('non-existent')).resolves.not.toThrow();
+    });
+```
+
+**New code**:
+```typescript
+    it('should handle non-existent session gracefully', async () => {
+      await expect(manager.stopSession('non-existent')).resolves.not.toThrow();
+      expect(manager.getSessionCount()).toBe(0);
+    });
+```
+
+### Verification
+
+Run each test file individually:
+
+```bash
+npx vitest run test/task-tracker.test.ts
+npx vitest run test/image-watcher.test.ts
+npx vitest run test/task-queue.test.ts
+npx vitest run test/hooks-config.test.ts
+npx vitest run test/session-manager.test.ts
+```
+
+**Important**: `hooks-config.test.ts` and `session-manager.test.ts` spawn real servers on ports 3130-3131. Only run them if you are NOT running other tests that use those ports.
+
+---
+
+## Final Verification Checklist
+
+After all 5 tasks are complete, run the following in order:
+
+```bash
+# 1. TypeScript type checking
+tsc --noEmit
+
+# 2. Linting
+npm run lint
+
+# 3. Formatting
+npm run format:check
+
+# 4. Run affected test files individually (NOT the full suite)
+npx vitest run test/string-utilities.test.ts
+npx vitest run test/task-tracker.test.ts
+npx vitest run test/image-watcher.test.ts
+npx vitest run test/task-queue.test.ts
+npx vitest run test/session-manager.test.ts
+npx vitest run test/hooks-config.test.ts
+```
+
+If any formatting issues arise, fix with:
+```bash
+npm run format
+```
+
+If any lint issues arise, fix with:
+```bash
+npm run lint:fix
+```
+
+### Summary of Changes
+
+| Task | Files Modified | Files Created |
+|------|---------------|---------------|
+| 1. Barrel exports | `src/utils/index.ts` | -- |
+| 2. Dead functions | `src/utils/string-similarity.ts` | -- |
+| 3. EXEC_TIMEOUT_MS | `src/utils/claude-cli-resolver.ts`, `src/utils/opencode-cli-resolver.ts`, `src/tmux-manager.ts` | `src/config/exec-timeout.ts` |
+| 4. z.infer types | `src/web/schemas.ts` | -- |
+| 5. Weak tests | `test/task-tracker.test.ts`, `test/image-watcher.test.ts`, `test/task-queue.test.ts`, `test/hooks-config.test.ts`, `test/session-manager.test.ts` | -- |
+
+**Total files modified**: 10
+**Total files created**: 1

docs/archive/phase6-config-consolidation-plan.md

@@ -0,0 +1,689 @@
+# Phase 6 Implementation Plan: Config Consolidation
+
+**Source**: `docs/code-structure-findings.md` (Phase 6 — Config Consolidation)
+**Estimated effort**: 1 day
+**Tasks**: 8 tasks with dependencies (see dependency graph below)
+
+---
+
+## Safety Constraints
+
+Before starting ANY work, read and follow these rules:
+
+1. **Never run `npx vitest run`** (full suite) — it kills tmux sessions. You are running inside a Codeman-managed tmux session.
+2. **Run individual tests only**: `npx vitest run test/<file>.test.ts`
+3. **Never test on port 3000** — the live dev server runs there. Tests use ports 3150+.
+4. **After TypeScript changes**: Run `tsc --noEmit` to verify type checking passes.
+5. **Before considering done**: Run `npm run lint` and `npm run format:check` to ensure CI passes.
+6. **Never kill tmux sessions** — check `echo $CODEMAN_MUX` first.
+7. **Verify the dev server starts**: After each task, run `npx tsx src/index.ts web --port 3099 &` on a non-production port, confirm `curl -s http://localhost:3099/api/status | jq .status` returns `"ok"`, then kill the background process.
+
+---
+
+## Goal
+
+Consolidate ~70 scattered numeric constants from 15+ source files into 6 new domain-focused config files, eliminating cross-file duplicates (including a 5x-duplicated AI model string) and making all tuning knobs discoverable in `src/config/`.
+
+**Non-goal**: Moving every constant. Module-internal implementation details (like regex patterns, algorithm-specific magic numbers, or constants only used once in deeply coupled logic) stay where they are. The goal is discoverability of operational tuning knobs, not mechanical relocation.
+
+---
+
+## Design Decisions
+
+### What gets centralized (and why)
+
+Constants are candidates for centralization when they meet **any** of these criteria:
+
+1. **Duplicated across files** — DRY violation (e.g., `STATS_COLLECTION_INTERVAL_MS` in `server.ts` and `mux-routes.ts`, AI model string in 5 files)
+2. **Operational tuning knobs** — values an operator might want to adjust for performance, security, or behavior without understanding the implementation (e.g., SSE health check interval, auth session TTL, rate limits)
+3. **Cross-cutting concerns** — values that establish system-wide contracts (e.g., max terminal dimensions used by both server routes and frontend)
+
+### What stays in place (and why)
+
+Constants that are **internal implementation details** of a single module stay where they are:
+
+- **Algorithm parameters** — `TODO_SIMILARITY_THRESHOLD`, `adaptiveCompletionConfirmMs`, confidence weights. These are meaningless without understanding the algorithm.
+- **Display/UI formatting** — `TEXT_PREVIEW_LENGTH`, `SMART_TITLE_MAX_LENGTH`, `COMMAND_DISPLAY_LENGTH` in `subagent-watcher.ts`. Only used locally, tightly coupled to rendering logic.
+- **Module-internal timing** — `LINE_BUFFER_FLUSH_INTERVAL` in `session.ts`, `AI_CHECK_POLL_INTERVAL` in `ai-checker-base.ts`. Internal implementation of specific features.
+- **Frontend constants** — `constants.js` already centralizes frontend values well. Don't mix frontend and backend config.
+- **Respawn `DEFAULT_CONFIG`** — these are user-configurable defaults for the respawn config interface, not system constants. They live properly in `respawn-controller.ts`. The AI model/context defaults within it are replaced with imports from the new `ai-defaults.ts` (Task 5).
+- **Session auto-ops thresholds** — `AUTO_RETRY_DELAY_MS`, `COMPACT_COOLDOWN_MS`, etc. in `session-auto-ops.ts` are internal to that module's retry logic and already well-documented in place.
+
+### File organization: domain-based, not category-based
+
+A single `timing-config.ts` with 70 unrelated timing values would be worse than the current state — developers would need to grep it just like they grep the whole codebase now. Instead, constants are grouped by **the system they configure**:
+
+| New File | Domain | Developer Question It Answers |
+|----------|--------|-------------------------------|
+| `server-timing.ts` | Web server performance | "How do I tune SSE batching / terminal throughput?" |
+| `auth-config.ts` | Authentication & security | "What are the rate limits and session TTLs?" |
+| `tunnel-config.ts` | QR auth & Cloudflare tunnel | "What are the QR token rotation parameters?" |
+| `terminal-limits.ts` | Terminal dimensions & input | "What are the max cols/rows/input size?" |
+| `ai-defaults.ts` | AI checker model & context | "What model do the AI checkers use? What's the context limit?" |
+| `team-config.ts` | Agent Teams polling & caching | "How often does team polling run? What are the cache limits?" |
+
+---
+
+## Task Dependencies
+
+```
+Task 1 (server-timing.ts)
+Task 2 (auth-config.ts)
+Task 3 (tunnel-config.ts)
+Task 4 (terminal-limits.ts)
+Task 5 (ai-defaults.ts)
+Task 6 (team-config.ts)
+    └──> Task 7 (Fix remaining duplicates)
+         └──> Task 8 (Update CLAUDE.md + final verification)
+```
+
+**Tasks 1–6** are independent and can run in parallel.
+**Task 7** depends on Tasks 1–6 (needs the new config files to exist).
+**Task 8** depends on Task 7.
+
+---
+
+## Task 1: Create `src/config/server-timing.ts`
+
+**Estimated effort**: 30 minutes
+**Files created**: `src/config/server-timing.ts`
+**Files modified**: `src/web/server.ts`, `src/web/routes/mux-routes.ts`
+
+### Constants to extract from `src/web/server.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `TERMINAL_BATCH_INTERVAL` | `16` | Terminal data batching interval (60fps) |
+| `TASK_UPDATE_BATCH_INTERVAL` | `100` | Task event batching interval (ms) |
+| `STATE_UPDATE_DEBOUNCE_INTERVAL` | `500` | State persistence debounce (ms) |
+| `SESSIONS_LIST_CACHE_TTL` | `1000` | Sessions list cache TTL (ms) |
+| `SCHEDULED_CLEANUP_INTERVAL` | `300000` | Scheduled runs cleanup check (5 min) |
+| `SCHEDULED_RUN_MAX_AGE` | `3600000` | Completed scheduled run max age (1 hour) |
+| `SSE_HEALTH_CHECK_INTERVAL` | `30000` | SSE client health check (30s) |
+| `SESSION_LIMIT_WAIT_MS` | `5000` | Session limit retry wait (5s) |
+| `ITERATION_PAUSE_MS` | `2000` | Scheduled run iteration pause (2s) |
+| `BATCH_FLUSH_THRESHOLD` | `32768` | Terminal batch immediate flush threshold (32KB) |
+| `STATS_COLLECTION_INTERVAL_MS` | `2000` | Mux stats collection interval (2s) |
+
+### Implementation
+
+1. Create `src/config/server-timing.ts` with all 11 constants, preserving existing JSDoc comments.
+2. In `src/web/server.ts`: Remove the 11 local constant declarations (lines ~92–121). Add `import { TERMINAL_BATCH_INTERVAL, ... } from '../config/server-timing.js'`.
+3. In `src/web/routes/mux-routes.ts`: Remove the duplicate `STATS_COLLECTION_INTERVAL_MS` (line 10) and its comment. Add `import { STATS_COLLECTION_INTERVAL_MS } from '../../config/server-timing.js'`. This fixes a **duplicate constant** (finding #10).
+4. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Web server performance and scheduling constants.
+ *
+ * Controls terminal batching throughput, SSE health checking,
+ * state persistence debouncing, and scheduled run timing.
+ *
+ * @module config/server-timing
+ */
+
+// ============================================================================
+// Terminal & SSE Performance
+// ============================================================================
+
+/** Terminal data batching interval — targets 60fps (ms) */
+export const TERMINAL_BATCH_INTERVAL = 16;
+
+/** Immediate flush threshold for terminal batches (bytes).
+ * Set high (32KB) to allow effective batching; avg Ink events are ~14KB. */
+export const BATCH_FLUSH_THRESHOLD = 32 * 1024;
+
+/** Task event batching interval (ms) */
+export const TASK_UPDATE_BATCH_INTERVAL = 100;
+
+/** SSE client health check interval (ms) */
+export const SSE_HEALTH_CHECK_INTERVAL = 30 * 1000;
+
+// ============================================================================
+// State Persistence
+// ============================================================================
+
+/** State update debounce — batches expensive toDetailedState() calls (ms) */
+export const STATE_UPDATE_DEBOUNCE_INTERVAL = 500;
+
+/** Sessions list cache TTL — avoids re-serializing on every SSE init (ms) */
+export const SESSIONS_LIST_CACHE_TTL = 1000;
+
+// ============================================================================
+// Scheduled Runs
+// ============================================================================
+
+/** Scheduled runs cleanup check interval (ms) */
+export const SCHEDULED_CLEANUP_INTERVAL = 5 * 60 * 1000;
+
+/** Completed scheduled run max age before cleanup (ms) */
+export const SCHEDULED_RUN_MAX_AGE = 60 * 60 * 1000;
+
+/** Session limit retry wait before retrying (ms) */
+export const SESSION_LIMIT_WAIT_MS = 5000;
+
+/** Pause between scheduled run iterations (ms) */
+export const ITERATION_PAUSE_MS = 2000;
+
+// ============================================================================
+// Mux Stats
+// ============================================================================
+
+/** Mux stats collection interval (ms) */
+export const STATS_COLLECTION_INTERVAL_MS = 2000;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+npx tsx src/index.ts web --port 3099 &
+curl -s http://localhost:3099/api/status | jq .status  # "ok"
+kill %1
+```
+
+---
+
+## Task 2: Create `src/config/auth-config.ts`
+
+**Estimated effort**: 20 minutes
+**Files created**: `src/config/auth-config.ts`
+**Files modified**: `src/web/middleware/auth.ts`, `src/hooks-config.ts`
+
+### Constants to extract from `src/web/middleware/auth.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `AUTH_SESSION_TTL_MS` | `86400000` | Auth session cookie TTL (24h) |
+| `MAX_AUTH_SESSIONS` | `100` | Max concurrent auth sessions |
+| `AUTH_FAILURE_MAX` | `10` | Max failed auth attempts per IP |
+| `AUTH_FAILURE_WINDOW_MS` | `900000` | Failed auth tracking window (15 min) |
+
+### Constants to extract from `src/hooks-config.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `HOOK_TIMEOUT_MS` | `10000` | Timeout for Claude Code hook commands |
+
+The `timeout: 10000` value is hardcoded 6 times in `hooks-config.ts` as inline literals. Extract to a single named constant.
+
+### Implementation
+
+1. Create `src/config/auth-config.ts` with the 5 constants.
+2. In `src/web/middleware/auth.ts`: Remove the 4 local constant declarations (lines 17–25). Add import from `../../config/auth-config.js`. Keep `AUTH_COOKIE_NAME` in place — it's a string identifier, not a tunable numeric constant.
+3. In `src/hooks-config.ts`: Replace all 6 inline `timeout: 10000` occurrences with `timeout: HOOK_TIMEOUT_MS`. Add import from `./config/auth-config.js`.
+4. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Authentication, rate limiting, and hook security constants.
+ *
+ * Controls auth session lifecycle, brute-force protection,
+ * and Claude Code hook timeouts.
+ *
+ * @module config/auth-config
+ */
+
+// ============================================================================
+// Session Cookies
+// ============================================================================
+
+/** Auth session cookie TTL — matches autonomous run length (ms) */
+export const AUTH_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Max concurrent auth sessions per server */
+export const MAX_AUTH_SESSIONS = 100;
+
+// ============================================================================
+// Rate Limiting
+// ============================================================================
+
+/** Max failed auth attempts per IP before 429 rejection */
+export const AUTH_FAILURE_MAX = 10;
+
+/** Failed auth attempt tracking window (ms) */
+export const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+/** Timeout for Claude Code hook curl commands (ms) */
+export const HOOK_TIMEOUT_MS = 10000;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+npm run lint
+```
+
+---
+
+## Task 3: Create `src/config/tunnel-config.ts`
+
+**Estimated effort**: 20 minutes
+**Files created**: `src/config/tunnel-config.ts`
+**Files modified**: `src/tunnel-manager.ts`
+
+### Constants to extract from `src/tunnel-manager.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `QR_TOKEN_TTL_MS` | `60000` | QR token auto-rotation interval (60s) |
+| `QR_TOKEN_GRACE_MS` | `90000` | Grace period for previous token (90s) |
+| `SHORT_CODE_LENGTH` | `6` | Length of QR short code |
+| `QR_RATE_LIMIT_MAX` | `30` | Global QR attempt rate limit |
+| `QR_RATE_LIMIT_WINDOW_MS` | `60000` | QR rate limit reset window (60s) |
+| `URL_TIMEOUT_MS` | `30000` | Cloudflared URL fetch timeout (30s) |
+| `RESTART_DELAY_MS` | `5000` | Tunnel restart delay after crash (5s) |
+| `FORCE_KILL_MS` | `5000` | SIGTERM → SIGKILL escalation timeout (5s) |
+
+### Implementation
+
+1. Create `src/config/tunnel-config.ts` with all 8 constants.
+2. In `src/tunnel-manager.ts`: Remove the 8 local constant declarations (lines ~39–75). Add `import { QR_TOKEN_TTL_MS, ... } from './config/tunnel-config.js'`.
+3. Keep the `TUNNEL_URL_REGEX` in `tunnel-manager.ts` — it's a parsing detail, not a tuning knob.
+4. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Cloudflare tunnel and QR authentication constants.
+ *
+ * Controls QR token rotation timing, rate limiting,
+ * and tunnel process lifecycle.
+ *
+ * @module config/tunnel-config
+ */
+
+// ============================================================================
+// QR Token Rotation
+// ============================================================================
+
+/** QR token auto-rotation interval (ms) */
+export const QR_TOKEN_TTL_MS = 60_000;
+
+/** Grace period — previous token still valid during rotation (ms) */
+export const QR_TOKEN_GRACE_MS = 90_000;
+
+/** Length of the short code in QR URL path (chars) */
+export const SHORT_CODE_LENGTH = 6;
+
+// ============================================================================
+// QR Rate Limiting
+// ============================================================================
+
+/** Global rate limit for QR auth attempts across all IPs */
+export const QR_RATE_LIMIT_MAX = 30;
+
+/** QR rate limit reset window (ms) */
+export const QR_RATE_LIMIT_WINDOW_MS = 60_000;
+
+// ============================================================================
+// Tunnel Process Lifecycle
+// ============================================================================
+
+/** Max time to wait for cloudflared URL before timeout (ms) */
+export const URL_TIMEOUT_MS = 30_000;
+
+/** Restart delay after unexpected tunnel exit (ms) */
+export const RESTART_DELAY_MS = 5_000;
+
+/** SIGTERM → SIGKILL escalation timeout (ms) */
+export const FORCE_KILL_MS = 5_000;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 4: Create `src/config/terminal-limits.ts`
+
+**Estimated effort**: 20 minutes
+**Files created**: `src/config/terminal-limits.ts`
+**Files modified**: `src/web/routes/session-routes.ts`
+
+### Constants to extract from `src/web/routes/session-routes.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `MAX_INPUT_LENGTH` | `65536` | Max input length per request (64KB) |
+| `MAX_TERMINAL_COLS` | `500` | Max terminal columns |
+| `MAX_TERMINAL_ROWS` | `200` | Max terminal rows |
+| `MAX_SESSION_NAME_LENGTH` | `128` | Max session name length (chars) |
+
+### Why a separate file instead of adding to `buffer-limits.ts`
+
+`buffer-limits.ts` covers memory buffer sizes (2MB terminal, 1MB text). These constants are **validation limits** for API inputs — different concern. A terminal resize request must not exceed `MAX_TERMINAL_COLS`; this has nothing to do with buffer trimming.
+
+### Implementation
+
+1. Create `src/config/terminal-limits.ts` with all 4 constants.
+2. In `src/web/routes/session-routes.ts`: Remove the 4 local constant declarations (lines 45–48). Add `import { MAX_INPUT_LENGTH, MAX_TERMINAL_COLS, MAX_TERMINAL_ROWS, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js'`.
+3. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Terminal dimension and input validation limits.
+ *
+ * Used by API routes to validate resize, input, and session
+ * creation requests. Separate from buffer-limits.ts which
+ * controls memory buffer sizes.
+ *
+ * @module config/terminal-limits
+ */
+
+/** Max input length per API request (bytes) */
+export const MAX_INPUT_LENGTH = 64 * 1024;
+
+/** Max terminal columns for resize requests */
+export const MAX_TERMINAL_COLS = 500;
+
+/** Max terminal rows for resize requests */
+export const MAX_TERMINAL_ROWS = 200;
+
+/** Max session name length (chars) */
+export const MAX_SESSION_NAME_LENGTH = 128;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 5: Create `src/config/ai-defaults.ts`
+
+**Estimated effort**: 30 minutes
+**Files created**: `src/config/ai-defaults.ts`
+**Files modified**: `src/respawn-controller.ts`, `src/ai-idle-checker.ts`, `src/ai-plan-checker.ts`, `src/web/routes/respawn-routes.ts`
+
+### Problem: AI model string duplicated 5 times
+
+The model identifier `'claude-opus-4-5-20251101'` appears in 5 places across 4 files. When the model changes, all 5 must be updated — a guaranteed source of bugs. The context limits (`16000`, `8000`) are similarly scattered across 3 files each.
+
+| Constant | Current Value | Duplicated In |
+|----------|---------------|---------------|
+| `AI_CHECK_MODEL` | `'claude-opus-4-5-20251101'` | `respawn-controller.ts` (×2: idle + plan), `ai-idle-checker.ts`, `ai-plan-checker.ts`, `respawn-routes.ts` (×2: idle + plan) |
+| `AI_IDLE_CHECK_MAX_CONTEXT` | `16000` | `respawn-controller.ts`, `ai-idle-checker.ts`, `respawn-routes.ts` |
+| `AI_PLAN_CHECK_MAX_CONTEXT` | `8000` | `respawn-controller.ts`, `ai-plan-checker.ts`, `respawn-routes.ts` |
+
+### Implementation
+
+1. Create `src/config/ai-defaults.ts` with the 3 constants.
+2. In `src/respawn-controller.ts` `DEFAULT_CONFIG` (line 538): Replace `aiIdleCheckModel: 'claude-opus-4-5-20251101'` with `aiIdleCheckModel: AI_CHECK_MODEL`, `aiIdleCheckMaxContext: 16000` with `aiIdleCheckMaxContext: AI_IDLE_CHECK_MAX_CONTEXT`, `aiPlanCheckModel: 'claude-opus-4-5-20251101'` with `aiPlanCheckModel: AI_CHECK_MODEL`, `aiPlanCheckMaxContext: 8000` with `aiPlanCheckMaxContext: AI_PLAN_CHECK_MAX_CONTEXT`. Add import from `./config/ai-defaults.js`.
+3. In `src/ai-idle-checker.ts` `DEFAULT_AI_CHECK_CONFIG` (line 46): Replace `model: 'claude-opus-4-5-20251101'` with `model: AI_CHECK_MODEL`, `maxContextChars: 16000` with `maxContextChars: AI_IDLE_CHECK_MAX_CONTEXT`. Add import from `./config/ai-defaults.js`.
+4. In `src/ai-plan-checker.ts` `DEFAULT_PLAN_CHECK_CONFIG` (line 45): Replace `model: 'claude-opus-4-5-20251101'` with `model: AI_CHECK_MODEL`, `maxContextChars: 8000` with `maxContextChars: AI_PLAN_CHECK_MAX_CONTEXT`. Add import from `./config/ai-defaults.js`.
+5. In `src/web/routes/respawn-routes.ts` config merge block (lines 173–179): Replace all 4 inline fallback values with imports from `../../config/ai-defaults.js`.
+6. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Default model and context limits for AI-powered checkers.
+ *
+ * Centralizes the AI model identifier and context window sizes used by
+ * the idle checker, plan checker, respawn controller defaults, and
+ * respawn route fallbacks. Change the model here when upgrading.
+ *
+ * @module config/ai-defaults
+ */
+
+/** Default model for AI idle and plan checkers */
+export const AI_CHECK_MODEL = 'claude-opus-4-5-20251101';
+
+/** Max context chars for idle checker (~4k tokens) */
+export const AI_IDLE_CHECK_MAX_CONTEXT = 16000;
+
+/** Max context chars for plan checker (~2k tokens, plan mode UI is compact) */
+export const AI_PLAN_CHECK_MAX_CONTEXT = 8000;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+# Verify no remaining hardcoded model strings
+grep -rn 'claude-opus-4-5-20251101' src/  # Should only appear in config/ai-defaults.ts
+```
+
+---
+
+## Task 6: Create `src/config/team-config.ts`
+
+**Estimated effort**: 15 minutes
+**Files created**: `src/config/team-config.ts`
+**Files modified**: `src/team-watcher.ts`
+
+### Constants to extract from `src/team-watcher.ts`
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `TEAM_POLL_INTERVAL_MS` | `30000` | Team directory poll interval (30s) |
+| `MAX_CACHED_TEAMS` | `50` | LRU cache size for team configs |
+| `MAX_CACHED_TASKS` | `200` | LRU cache size for team tasks + inboxes |
+
+### Why centralize these
+
+Team polling frequency and cache sizes are operational knobs that affect both performance (polling too often wastes CPU) and responsiveness (polling too rarely means stale team state in the UI). They're also the kind of values a developer tuning for a large team deployment would want to find quickly. `MAX_CACHED_TASKS` is used for both the task cache and inbox cache — worth documenting.
+
+### Implementation
+
+1. Create `src/config/team-config.ts` with the 3 constants.
+2. In `src/team-watcher.ts`: Remove the 3 local constants (lines 23–25). Add `import { TEAM_POLL_INTERVAL_MS, MAX_CACHED_TEAMS, MAX_CACHED_TASKS } from './config/team-config.js'`. Note: rename `POLL_INTERVAL_MS` → `TEAM_POLL_INTERVAL_MS` to avoid ambiguity with the identically-named constant in `subagent-watcher.ts`.
+3. Update the usage site: `setInterval(... POLL_INTERVAL_MS)` → `setInterval(... TEAM_POLL_INTERVAL_MS)`.
+4. Run `tsc --noEmit`.
+
+### New file template
+
+```typescript
+/**
+ * @fileoverview Agent Teams polling and cache configuration.
+ *
+ * Controls how frequently TeamWatcher polls ~/.claude/teams/
+ * and how many teams/tasks are cached in memory.
+ *
+ * @module config/team-config
+ */
+
+/** Team directory poll interval (ms) */
+export const TEAM_POLL_INTERVAL_MS = 30_000;
+
+/** Max cached team configs (LRU eviction) */
+export const MAX_CACHED_TEAMS = 50;
+
+/** Max cached team tasks and inbox messages (LRU eviction).
+ * Used for both teamTasks and inboxCache maps. */
+export const MAX_CACHED_TASKS = 200;
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 7: Fix remaining cross-file duplicates
+
+**Estimated effort**: 30 minutes
+**Files modified**: `src/index.ts`, `src/subagent-watcher.ts`
+
+### Duplicate 1: `STATS_COLLECTION_INTERVAL_MS`
+
+Already fixed in Task 1 — both `server.ts` and `mux-routes.ts` now import from `server-timing.ts`.
+
+### Duplicate 2: AI model string
+
+Already fixed in Task 5 — all 5 occurrences now import from `ai-defaults.ts`.
+
+### Duplicate 3: `MAX_SCREENSHOT_SIZE` / `MAX_TEXT_FILE_SIZE` / `MAX_RAW_FILE_SIZE`
+
+These file size limits in `file-routes.ts` and `system-routes.ts` are **API-specific validation limits**. They're only used in their respective route files and aren't duplicated. **Leave in place** — they're local to their route module and well-commented.
+
+### Action A: Move `MAX_CONSECUTIVE_ERRORS` and `ERROR_RESET_MS` to config
+
+`src/index.ts` has two process-level constants that are operational tuning knobs:
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `MAX_CONSECUTIVE_ERRORS` | `5` | Max consecutive unhandled errors before process exit |
+| `ERROR_RESET_MS` | `60000` | Error counter reset interval (1 min) |
+
+These belong in a config file since they control server reliability behavior. Add them to `src/config/server-timing.ts` (they're server operational constants).
+
+1. Add to `src/config/server-timing.ts`:
+   ```typescript
+   // ============================================================================
+   // Process Error Recovery
+   // ============================================================================
+
+   /** Max consecutive unhandled errors before auto-restart */
+   export const MAX_CONSECUTIVE_ERRORS = 5;
+
+   /** Error counter reset interval — forgives errors after quiet period (ms) */
+   export const ERROR_RESET_MS = 60_000;
+   ```
+2. In `src/index.ts`: Remove lines 19–20, add import from `./config/server-timing.js`.
+3. Run `tsc --noEmit`.
+
+### Action B: Fix `MAX_TRACKED_AGENTS` shadow in `subagent-watcher.ts`
+
+`subagent-watcher.ts` defines its own `MAX_TRACKED_AGENTS = 500` locally instead of importing the identical value from `config/map-limits.ts`. This is a latent bug — if someone changes the config value, the subagent watcher's copy stays stale.
+
+1. In `src/subagent-watcher.ts`: Remove the local `MAX_TRACKED_AGENTS` constant. Add `import { MAX_TRACKED_AGENTS } from './config/map-limits.js'` (the value there is `MAX_TODOS_PER_SESSION = 500` — **verify** the map-limits constant is actually named `MAX_TRACKED_AGENTS` or if it needs to be added). If the constant doesn't exist in `map-limits.ts` under that name, add it.
+2. Run `tsc --noEmit`.
+
+### Verification
+
+```bash
+tsc --noEmit
+npm run lint
+npm run format:check
+```
+
+---
+
+## Task 8: Update CLAUDE.md and final verification
+
+**Estimated effort**: 20 minutes
+**Files modified**: `CLAUDE.md`
+
+### Updates to CLAUDE.md
+
+1. **Config Files table** (`src/config/`): Add the 6 new files:
+
+   | File | Purpose |
+   |------|---------|
+   | `buffer-limits.ts` | Terminal/text buffer size limits |
+   | `map-limits.ts` | Global limits for Maps, sessions, watchers |
+   | `exec-timeout.ts` | Execution timeout configuration |
+   | `server-timing.ts` | Web server batching, SSE, scheduled run timing |
+   | `auth-config.ts` | Auth session TTL, rate limits, hook timeout |
+   | `tunnel-config.ts` | QR token rotation, tunnel process lifecycle |
+   | `terminal-limits.ts` | Terminal dimension and input validation limits |
+   | `ai-defaults.ts` | AI checker model and context limits |
+   | `team-config.ts` | Agent Teams polling and cache sizes |
+
+2. **Import Conventions** section: Add:
+   ```
+   - **Config**: Import from specific files: `import { MAX_TERMINAL_COLS } from './config/terminal-limits'`
+   ```
+
+3. **Phase 6 status** in `docs/code-structure-findings.md`: Mark as COMPLETE with summary of what was done.
+
+### Final verification checklist
+
+```bash
+# Type checking
+tsc --noEmit
+
+# Linting
+npm run lint
+
+# Formatting
+npm run format:check
+
+# Dev server starts
+npx tsx src/index.ts web --port 3099 &
+curl -s http://localhost:3099/api/status | jq .status  # "ok"
+kill %1
+
+# Verify no remaining duplicates
+grep -rn 'STATS_COLLECTION_INTERVAL_MS' src/  # Should only appear in config + import sites
+grep -rn 'timeout: 10000' src/hooks-config.ts  # Should be 0 — all replaced with HOOK_TIMEOUT_MS
+grep -rn 'claude-opus-4-5-20251101' src/       # Should only appear in config/ai-defaults.ts
+```
+
+---
+
+## What is NOT in scope (and why)
+
+These constants were considered but deliberately left in their current files:
+
+### Respawn controller defaults (`src/respawn-controller.ts`)
+
+The `DEFAULT_CONFIG` object (lines 538–578) contains ~30 default values for the `RespawnConfig` interface. These are **user-facing configuration defaults**, not system constants — they're the starting values for a config object that users can modify via the API and UI. Centralizing them would break the locality between the config interface definition and its defaults. They already have excellent JSDoc with `@default` tags. The only values extracted are the AI model/context constants (Task 5) which are duplicated in other files.
+
+### Subagent watcher timing (`src/subagent-watcher.ts`)
+
+The 18 constants at lines 129–158 are all internal to the subagent watcher's polling/lifecycle algorithm. Moving them to a config file would force developers to context-switch between two files to understand the polling logic. They're already grouped with clear comments. Exception: `MAX_TRACKED_AGENTS` is consolidated with `map-limits.ts` (Task 7B) since it duplicates a global limit.
+
+### Session auto-ops timing (`src/session-auto-ops.ts`)
+
+The 8 constants at lines 19–40 are internal to the auto-compact/clear retry state machine. They form a coherent group that's meaningless without the surrounding implementation context.
+
+### Run summary constants (`src/run-summary.ts`)
+
+`MAX_EVENTS`, `TRIM_TO_EVENTS`, `TOKEN_MILESTONE_INTERVAL`, `STATE_STUCK_WARNING_MS`, `STATE_STUCK_CHECK_INTERVAL` — all module-internal. The buffer-style limits (`MAX_EVENTS`/`TRIM_TO_EVENTS`) follow the same pattern as `buffer-limits.ts` but are only used in this one file.
+
+### Frontend (`src/web/public/constants.js`)
+
+Already well-centralized. Frontend and backend run in different environments — mixing them in TypeScript config files would create import problems. If frontend constants need expansion, do it in `constants.js`. Note: `app.js` has 2 inline uses of `256 * 1024` that should use the existing `TERMINAL_TAIL_SIZE` from `constants.js` — a minor cleanup that can be done opportunistically but is not worth a task here.
+
+### Tmux manager timing (`src/tmux-manager.ts`)
+
+The 6 constants (lines 65–78) are internal to tmux process lifecycle management. They're low-level retry/wait values that are meaningless without understanding the tmux spawn sequence.
+
+### Process-internal constants
+
+`image-watcher.ts`, `bash-tool-parser.ts`, `transcript-watcher.ts`, `ralph-tracker.ts`, `task-tracker.ts`, `file-stream-manager.ts`, `session-lifecycle-log.ts`, `session-task-cache.ts`, `respawn-metrics.ts`, `respawn-adaptive-timing.ts`, `ai-checker-base.ts` — all have module-local constants that are internal implementation details.
+
+### `localhost:3000` default URL
+
+The string `'http://localhost:3000'` or port `3000` appears as a fallback default in ~5 files (`session-cli-builder.ts`, `tmux-manager.ts`, `tunnel-manager.ts`, `server.ts`, CLI). While technically duplicated, extracting it provides little value — each usage has a different fallback chain (env var → config → hardcoded) and the port is also baked into systemd service files and documentation. The risk of a missed update is low since port 3000 is deeply conventional.
+
+### `SAVE_DEBOUNCE_MS = 500` in `state-store.ts` / `push-store.ts`
+
+Same value (500ms), but they debounce different persistence targets (state.json vs push-subscriptions.json). If one needed faster/slower debouncing, they'd diverge. Coupling them would be misleading.
+
+---
+
+## Summary
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Config files in `src/config/` | 3 | 9 |
+| Constants centralized | ~25 | ~65 |
+| Cross-file duplicates | 9+ (`STATS_COLLECTION_INTERVAL_MS`, `timeout: 10000` ×6, AI model ×5, context limits ×3 each, `MAX_TRACKED_AGENTS`) | 0 |
+| Files with `timeout: 10000` inline | 1 (6 occurrences) | 0 |
+| Files with hardcoded AI model string | 4 (5 occurrences) | 1 (config only) |
+| Files modified | — | 11 |
+| Files created | — | 6 |

docs/archive/phase7-test-infrastructure-plan.md

@@ -0,0 +1,953 @@
+# Phase 7 Implementation Plan: Test Infrastructure
+
+**Source**: `docs/code-structure-findings.md` (Phase 7 — Test Infrastructure)
+**Estimated effort**: 2–3 days
+**Tasks**: 11 tasks with dependencies (see dependency graph below)
+
+---
+
+## Safety Constraints
+
+Before starting ANY work, read and follow these rules:
+
+1. **Never run `npx vitest run`** (full suite) — it kills tmux sessions. You are running inside a Codeman-managed tmux session.
+2. **Run individual tests only**: `npx vitest run test/<file>.test.ts`
+3. **Never test on port 3000** — the live dev server runs there. Tests use ports 3150+.
+4. **After TypeScript changes**: Run `tsc --noEmit` to verify type checking passes.
+5. **Before considering done**: Run `npm run lint` and `npm run format:check` to ensure CI passes.
+6. **Never kill tmux sessions** — check `echo $CODEMAN_MUX` first.
+7. **Port assignments for this phase**: New tests use ports 3220–3229 (see individual tasks for assignments).
+
+---
+
+## Goal
+
+Eliminate duplicated test mocks, activate the unused `respawn-test-utils.ts` utilities, and add route-level test coverage for the server's 12 route modules — the single largest untested area in the codebase (162 route handlers, 0 dedicated tests).
+
+**Non-goals**:
+- Full end-to-end integration tests (those require real Claude CLI / tmux sessions)
+- 100% route coverage in this phase — focus on the highest-value route modules first
+- Refactoring test patterns in existing passing tests that don't use shared mocks
+- Migrating `vi.mock()`-based module replacement mocks (different pattern, see Task 6/7)
+
+---
+
+## Current State
+
+### Mock Duplication (Finding #9)
+
+`MockSession` is defined **4 times** across test files with varying levels of completeness:
+
+| File | Properties | Methods | EventEmitter | Notes |
+|------|-----------|---------|-------------|-------|
+| `test/respawn-test-utils.ts` | 6 | 20+ | Yes | **Most complete**. Includes terminal simulation, token count, ANSI output, plan mode prompts. **Never imported by any test.** |
+| `test/respawn-controller.test.ts` | 6 | 9 | Yes | Subset of respawn-test-utils. Missing token simulation, ANSI helpers. |
+| `test/respawn-team-awareness.test.ts` | ~6 | ~9 | Yes | Near-copy of respawn-controller.test.ts version. |
+| `test/session-manager.test.ts` | 4 | 8 | Yes | **Inside `vi.mock()` factory** — replaces `../src/session.js` module. Different shape: `start()`/`stop()`/`toState()`/`sendInput()` for lifecycle testing. |
+
+`MockStateStore` is defined **2 times** (both inside `vi.mock()` factories):
+
+| File | Shape | Methods | Mock Pattern |
+|------|-------|---------|-------------|
+| `test/session-manager.test.ts` | `{ sessions, config }` | `getConfig`, `getSessions`, `getSession`, `setSession`, `removeSession` | `vi.mock('../src/state-store.js')` |
+| `test/ralph-loop.test.ts` | `{ ralphLoop, tasks, config }` | `getConfig`, `getRalphLoopState`, `setRalphLoopState`, `getTasks`, `setTask`, `removeTask` | `vi.mock('../src/state-store.js')` |
+
+### Important: Two distinct mocking patterns
+
+The codebase uses two different mocking patterns that require different migration strategies:
+
+1. **Direct instantiation** (respawn-controller, respawn-team-awareness): `MockSession` is defined at file scope and instantiated directly in tests. These can be migrated to shared mocks via simple import replacement.
+
+2. **Module replacement** (session-manager, ralph-loop): Mocks are defined inside `vi.mock()` factories that replace entire modules (`../src/session.js`, `../src/state-store.js`). These factories run in an isolated scope and return `{ Session: MockClass }` or `{ getStore: vi.fn(() => instance) }`. Migrating these requires either `vi.hoisted()` or restructuring the test's module mocking — higher risk for limited benefit.
+
+### Unused Test Utilities
+
+`test/respawn-test-utils.ts` exports these utilities that **no test file imports**:
+
+- `TimeController` / `createTimeController()` — abstraction over vitest fake timers
+- `MockAiIdleChecker` / `MockAiPlanChecker` — fully mocked AI checkers with result queueing
+- `createStateTracker()` / `createEventRecorder()` — state transition and event recording
+- `FAST_TEST_CONFIG` / `AI_ENABLED_TEST_CONFIG` — pre-configured RespawnConfig objects
+- `waitForState()` / `waitForEvent()` / `createDeferred()` — async test helpers
+- `terminalOutputs` — factory object for common terminal output patterns
+
+### Route Test Coverage
+
+Currently **zero** dedicated tests for the 12 route modules in `src/web/routes/`. The existing test files that touch API endpoints:
+
+| Test File | What It Tests | Approach |
+|-----------|--------------|----------|
+| `test/api-responses.test.ts` | Response structure validation | Imports types, no HTTP calls |
+| `test/api-generate-plan.test.ts` | Plan generation API | Mocks validation logic, Port 3191 declared |
+| `test/auth-security.test.ts` | Auth middleware | Integration tests with WebServer, Ports 3160/3161 |
+| `test/qr-auth.test.ts` | QR authentication | Integration + unit tests, Port 3162 |
+
+None of these test the route handlers themselves with real HTTP requests against a running Fastify instance.
+
+---
+
+## Design Decisions
+
+### Shared mocks: Superset strategy
+
+Rather than creating a lowest-common-denominator mock, `MockSession` in `test/mocks/` will be the **superset** from `respawn-test-utils.ts` (the most complete version). Test files that need a simpler mock can just ignore the extra methods — having unused methods costs nothing, but missing methods forces local re-definition.
+
+### vi.mock() tests: Don't migrate
+
+The `session-manager.test.ts` and `ralph-loop.test.ts` tests define mocks inside `vi.mock()` factories. These use **module-level replacement** (replacing `../src/session.js` and `../src/state-store.js` entirely), which is fundamentally different from the direct-instantiation pattern. Migrating them would require `vi.hoisted()` or factory restructuring — high complexity for limited benefit since these mocks are already working. We leave these as-is and create the shared mocks for **new** tests and for the two direct-instantiation tests (Tasks 4–5).
+
+### MockStateStore: Union of both shapes
+
+The shared `MockStateStore` in `test/mocks/` will include methods from both existing definitions (session management + Ralph loop), so any **new** test can use it. Methods default to no-ops via `vi.fn()`. Existing `vi.mock()`-based tests are not migrated.
+
+### Route testing strategy: Lightweight Fastify instances
+
+Each route test file will:
+1. Create a minimal `Fastify` instance
+2. Register **only** the route module under test
+3. Provide a mock context object satisfying the port interfaces
+4. Use `app.inject()` (Fastify's built-in test helper) — no real HTTP, no port needed
+
+This avoids port conflicts entirely and runs fast. Only tests that need SSE or WebSocket behavior will use a real listening server with assigned ports.
+
+### Port assignments (for tests needing real servers)
+
+| Port | Test File | Purpose |
+|------|-----------|---------|
+| 3220 | `test/routes/session-routes.test.ts` | SSE integration (if needed) |
+| 3221 | `test/routes/system-routes.test.ts` | Status/stats endpoints |
+| 3222 | `test/routes/respawn-routes.test.ts` | Respawn API |
+| 3223 | `test/routes/ralph-routes.test.ts` | Ralph API |
+| 3224–3229 | Reserved | Future route tests |
+
+Most tests should NOT need real ports — `app.inject()` is preferred. Verified: ports 3220–3229 are completely unused by existing tests (highest used port is 3211 in `opencode-resize.test.ts`).
+
+---
+
+## Task Dependencies
+
+```
+Task 1 (Consolidate MockSession)
+Task 2 (Consolidate MockStateStore)
+    └──> Task 3 (Create test/mocks/ barrel)
+         ├──> Task 4 (Migrate respawn-controller.test.ts)
+         ├──> Task 5 (Migrate respawn-team-awareness.test.ts)
+         └──> Task 6 (Route test scaffold + helpers)
+              ├──> Task 7 (Session routes tests)
+              └──> Task 8 (System + respawn routes tests)
+
+Task 9 (Slim down respawn-test-utils.ts) — depends on Tasks 4, 5
+```
+
+**Tasks 1–2** are independent and can run in parallel.
+**Task 3** depends on Tasks 1–2.
+**Tasks 4–6** depend on Task 3 and can run in parallel.
+**Tasks 7–8** depend on Task 6 and can run in parallel.
+**Task 9** depends on Tasks 4, 5 (must verify migrations work before removing duplicates from source).
+
+---
+
+## Task 1: Consolidate MockSession into `test/mocks/mock-session.ts`
+
+**Estimated effort**: 2 hours
+**Files created**: `test/mocks/mock-session.ts`
+**Files modified**: None yet (consumers migrate in Tasks 4–5)
+
+### Source
+
+The canonical MockSession comes from `test/respawn-test-utils.ts` (lines 89–241). It is the most complete version with:
+
+- All properties needed by `RespawnController`: `id`, `workingDir`, `status`, `writeBuffer`, `terminalBuffer`, `muxName`
+- `write()` / `writeViaMux()` for input simulation
+- Buffer inspection: `lastWrite`, `hasWritten(pattern)`, `clearWriteBuffer()`
+- Terminal simulation: `simulateTerminalOutput()`, `simulatePrompt()`, `simulateReady()`, `simulateCompletionMessage()`, `simulateWorking()`, `simulateClearComplete()`, `simulateInitComplete()`, `simulatePlanModePrompt()`, `simulateElicitationDialog()`, `simulateTokenCount()`, `simulateAnsiOutput()`
+- Lifecycle: `close()`
+
+### Implementation
+
+1. Create `test/mocks/` directory.
+2. Create `test/mocks/mock-session.ts`:
+   - Copy the `MockSession` class **exactly** from `test/respawn-test-utils.ts` (lines 89–241)
+   - Copy `terminalOutputs` helper object (tightly coupled to mock)
+   - Copy `createMockSession()` factory function
+   - Export all three: `export { MockSession, createMockSession, terminalOutputs }`
+   - Ensure all `vi` imports come from `vitest`
+
+**CRITICAL**: Copy the source verbatim — do NOT rewrite the simulation methods. The respawn controller's detection logic matches specific output patterns (e.g., `'\u276f '` for prompt, `'\u273b Worked for'` for completion). Using different patterns would cause test failures.
+
+### Template
+
+```typescript
+/**
+ * Shared MockSession for tests that need terminal simulation.
+ *
+ * Copied from test/respawn-test-utils.ts (the canonical, most complete version).
+ * Used by respawn, route, and subagent tests.
+ */
+import { EventEmitter } from 'node:events';
+
+// Copy MockSession class exactly from test/respawn-test-utils.ts lines 89–241
+export class MockSession extends EventEmitter {
+  // ... (copy verbatim from respawn-test-utils.ts)
+}
+
+/**
+ * Factory for common terminal output strings.
+ * Must match the patterns used in MockSession's simulate* methods.
+ */
+export const terminalOutputs = {
+  // ... (copy verbatim from respawn-test-utils.ts)
+};
+
+/**
+ * Convenience factory.
+ */
+export function createMockSession(id?: string): MockSession {
+  return new MockSession(id);
+}
+```
+
+### Verification
+
+```bash
+tsc --noEmit  # Ensure file compiles
+```
+
+---
+
+## Task 2: Consolidate MockStateStore into `test/mocks/mock-state-store.ts`
+
+**Estimated effort**: 1 hour
+**Files created**: `test/mocks/mock-state-store.ts`
+**Files modified**: None (existing vi.mock()-based tests are NOT migrated; this is for new route tests)
+
+### Source
+
+Union of both existing definitions:
+
+- From `test/session-manager.test.ts`: session CRUD methods (`getConfig`, `getSession`, `setSession`, `removeSession`, `getSessions`)
+- From `test/ralph-loop.test.ts`: Ralph state methods (`getConfig`, `getRalphLoopState`, `setRalphLoopState`, `getTasks`, `setTask`, `removeTask`)
+
+### Template
+
+```typescript
+/**
+ * Shared MockStateStore for tests.
+ *
+ * Includes methods for both session management and Ralph loop testing.
+ * All methods are vi.fn() spies — tests can override return values as needed.
+ *
+ * NOTE: This is for direct instantiation in new tests. Existing tests that
+ * use vi.mock('../src/state-store.js') keep their inline definitions.
+ */
+import { vi } from 'vitest';
+
+export class MockStateStore {
+  state: Record<string, unknown> = {
+    sessions: {} as Record<string, unknown>,
+    config: { maxConcurrentSessions: 5 },
+    ralphLoop: { status: 'stopped' },
+    tasks: {} as Record<string, unknown>,
+  };
+
+  // Session methods
+  getConfig = vi.fn(() => this.state.config);
+  getSessions = vi.fn(() => this.state.sessions as Record<string, unknown>);
+  getSession = vi.fn((id: string) => (this.state.sessions as Record<string, unknown>)[id]);
+  setSession = vi.fn((id: string, state: unknown) => {
+    (this.state.sessions as Record<string, unknown>)[id] = state;
+  });
+  removeSession = vi.fn((id: string) => {
+    delete (this.state.sessions as Record<string, unknown>)[id];
+  });
+
+  // Ralph state methods
+  getRalphLoopState = vi.fn(() => this.state.ralphLoop);
+  setRalphLoopState = vi.fn((update: Record<string, unknown>) => {
+    this.state.ralphLoop = { ...(this.state.ralphLoop as Record<string, unknown>), ...update };
+  });
+
+  // Task methods
+  getTasks = vi.fn(() => this.state.tasks);
+  setTask = vi.fn();
+  removeTask = vi.fn();
+
+  // Settings methods
+  getSettings = vi.fn(() => ({}));
+  setSettings = vi.fn();
+
+  // Generic persistence
+  save = vi.fn();
+  load = vi.fn();
+
+  /** Reset all state and mocks for clean test isolation */
+  reset(): void {
+    this.state = {
+      sessions: {},
+      config: { maxConcurrentSessions: 5 },
+      ralphLoop: { status: 'stopped' },
+      tasks: {},
+    };
+    vi.clearAllMocks();
+  }
+}
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 3: Create `test/mocks/index.ts` barrel export
+
+**Estimated effort**: 30 minutes
+**Depends on**: Tasks 1, 2
+**Files created**: `test/mocks/index.ts`, `test/mocks/test-helpers.ts`
+**Files modified**: None
+
+### Implementation
+
+1. Create `test/mocks/test-helpers.ts` with the async utilities from `respawn-test-utils.ts`:
+
+```typescript
+/**
+ * Reusable async test helpers.
+ * Extracted from respawn-test-utils.ts.
+ */
+
+/** Wait for an EventEmitter to emit a specific event, with timeout */
+export function waitForEvent(
+  emitter: { once: (event: string, listener: (...args: unknown[]) => void) => void },
+  event: string,
+  timeoutMs = 5000,
+): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Timed out waiting for event "${event}" after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    emitter.once(event, (...args: unknown[]) => {
+      clearTimeout(timer);
+      resolve(args.length === 1 ? args[0] : args);
+    });
+  });
+}
+
+/** Create a deferred promise with external resolve/reject */
+export function createDeferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+```
+
+2. Create `test/mocks/index.ts` barrel:
+
+```typescript
+/**
+ * Shared test mocks — import from here instead of defining inline.
+ *
+ * @example
+ * import { MockSession, MockStateStore, terminalOutputs } from './mocks/index.js';
+ */
+
+export { MockSession, createMockSession, terminalOutputs } from './mock-session.js';
+export { MockStateStore } from './mock-state-store.js';
+export { waitForEvent, createDeferred } from './test-helpers.js';
+```
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 4: Migrate `respawn-controller.test.ts` to shared mocks
+
+**Estimated effort**: 30 minutes
+**Depends on**: Task 3
+**Files modified**: `test/respawn-controller.test.ts`
+
+### Steps
+
+1. Remove the local `MockSession` class definition (approx. 50 lines).
+2. Add: `import { MockSession } from './mocks/index.js';`
+3. Verify all test methods still exist on the shared mock. The shared mock is a superset, so all existing usage should work.
+4. If the local mock had any test-specific customizations (e.g., extra properties added in `beforeEach`), keep those in the test file as inline assignments on the shared instance.
+5. Run the test to confirm it passes.
+
+### Potential issues
+
+- The local mock's `simulateCompletionMessage()` may have a slightly different output format than the shared mock's (from respawn-test-utils.ts). Verify the respawn controller's completion detection regex matches the shared mock's output pattern (`'\u273b Worked for ...'`).
+- If the local mock adds `pid` or `isWorking` properties that the shared mock doesn't have, add inline assignments in `beforeEach`.
+
+### Verification
+
+```bash
+npx vitest run test/respawn-controller.test.ts
+```
+
+---
+
+## Task 5: Migrate `respawn-team-awareness.test.ts` to shared mocks
+
+**Estimated effort**: 30 minutes
+**Depends on**: Task 3
+**Files modified**: `test/respawn-team-awareness.test.ts`
+
+### Steps
+
+1. Remove the local `MockSession` class definition.
+2. Add: `import { MockSession } from './mocks/index.js';`
+3. Keep `MockTeamWatcher` in this file — it's test-specific and extends the real `TeamWatcher`, not a general-purpose mock.
+4. Run the test to confirm it passes.
+
+### Verification
+
+```bash
+npx vitest run test/respawn-team-awareness.test.ts
+```
+
+---
+
+## Task 6: Create route test scaffold and helpers
+
+**Estimated effort**: 2 hours
+**Depends on**: Task 3
+**Files created**: `test/mocks/mock-route-context.ts`, `test/routes/` directory, `test/routes/_route-test-utils.ts`
+
+### Problem
+
+The 12 route modules in `src/web/routes/` have zero dedicated test coverage. Each route module takes `(app: FastifyInstance, ctx: PortIntersection)` — we need a reusable way to create mock context objects that satisfy the port interfaces.
+
+### Design
+
+Create a `MockRouteContext` factory that builds a mock object satisfying all port interfaces. Each port's methods are `vi.fn()` stubs. Tests can override specific methods as needed.
+
+### Route registration signatures (verified)
+
+Each route module requires a specific port intersection. The mock must satisfy all of them:
+
+| Route Module | Required Ports |
+|-------------|----------------|
+| `registerSessionRoutes` | `SessionPort & EventPort & ConfigPort & InfraPort & AuthPort` |
+| `registerSystemRoutes` | `SessionPort & EventPort & ConfigPort & InfraPort & AuthPort` |
+| `registerRespawnRoutes` | `SessionPort & EventPort & RespawnPort & ConfigPort & InfraPort` |
+| `registerRalphRoutes` | `SessionPort & EventPort & RespawnPort & ConfigPort & InfraPort` |
+| `registerPlanRoutes` | `SessionPort & EventPort & ConfigPort & InfraPort` |
+| `registerCaseRoutes` | `EventPort & ConfigPort` |
+| `registerScheduledRoutes` | `SessionPort & EventPort & InfraPort` |
+| `registerFileRoutes` | `SessionPort` |
+| `registerMuxRoutes` | `InfraPort` |
+| `registerPushRoutes` | `InfraPort` |
+| `registerTeamRoutes` | `InfraPort` |
+| `registerHookEventRoutes` | `EventPort & AuthPort` |
+
+### Implementation
+
+1. Create `test/mocks/mock-route-context.ts`:
+
+```typescript
+/**
+ * Mock context for route handler testing.
+ *
+ * Satisfies ALL port interfaces (SessionPort, EventPort, RespawnPort,
+ * ConfigPort, InfraPort, AuthPort) so any route module can be tested.
+ * Override specific methods in individual tests as needed.
+ *
+ * Verified against actual port interfaces in src/web/ports/:
+ * - SessionPort: 6 methods (sessions, addSession, cleanupSession,
+ *   setupSessionListeners, persistSessionState, persistSessionStateNow,
+ *   getSessionStateWithRespawn)
+ * - EventPort: 5 methods (broadcast, sendPushNotifications, batchTerminalData,
+ *   broadcastSessionStateDebounced, batchTaskUpdate)
+ * - RespawnPort: 2 maps + 4 methods
+ * - ConfigPort: 5 readonly + 7 methods (incl getDefaultClaudeMdPath,
+ *   getLightState, getLightSessionsState, stopTranscriptWatcher)
+ * - InfraPort: 7 readonly + 2 methods (startScheduledRun, stopScheduledRun)
+ * - AuthPort: 3 readonly (authSessions, qrAuthFailures, https)
+ */
+import { vi } from 'vitest';
+import { MockSession, createMockSession } from './mock-session.js';
+
+/**
+ * Creates a mock context that satisfies all port interfaces.
+ * Pre-populated with one session for convenience.
+ */
+export function createMockRouteContext(options?: { sessionId?: string }) {
+  const sessionId = options?.sessionId ?? 'test-session-1';
+  const session = createMockSession(sessionId);
+  const sessions = new Map<string, MockSession>();
+  sessions.set(sessionId, session);
+
+  return {
+    // -- SessionPort --
+    sessions,
+    addSession: vi.fn(),
+    cleanupSession: vi.fn(),
+    setupSessionListeners: vi.fn(),
+    persistSessionState: vi.fn(),
+    persistSessionStateNow: vi.fn(),
+    getSessionStateWithRespawn: vi.fn((s: unknown) => s),
+
+    // -- EventPort --
+    broadcast: vi.fn(),
+    sendPushNotifications: vi.fn(),
+    batchTerminalData: vi.fn(),
+    broadcastSessionStateDebounced: vi.fn(),
+    batchTaskUpdate: vi.fn(),
+
+    // -- RespawnPort --
+    respawnControllers: new Map(),
+    respawnTimers: new Map(),
+    setupRespawnListeners: vi.fn(),
+    setupTimedRespawn: vi.fn(),
+    restoreRespawnController: vi.fn(),
+    saveRespawnConfig: vi.fn(),
+
+    // -- ConfigPort --
+    store: {
+      getConfig: vi.fn(() => ({})),
+      getSessions: vi.fn(() => ({})),
+      getSession: vi.fn(),
+      setSession: vi.fn(),
+      removeSession: vi.fn(),
+      getSettings: vi.fn(() => ({})),
+      setSettings: vi.fn(),
+      getRalphLoopState: vi.fn(() => ({})),
+      setRalphLoopState: vi.fn(),
+      getTasks: vi.fn(() => ({})),
+      save: vi.fn(),
+      load: vi.fn(),
+    },
+    port: 3000,
+    https: false,
+    testMode: true,
+    serverStartTime: Date.now(),
+    getGlobalNiceConfig: vi.fn(async () => undefined),
+    getModelConfig: vi.fn(async () => null),
+    getClaudeModeConfig: vi.fn(async () => ({})),
+    getDefaultClaudeMdPath: vi.fn(async () => undefined),
+    getLightState: vi.fn(() => ({ sessions: [], status: 'ok' })),
+    getLightSessionsState: vi.fn(() => []),
+    startTranscriptWatcher: vi.fn(),
+    stopTranscriptWatcher: vi.fn(),
+
+    // -- InfraPort --
+    mux: {
+      createSession: vi.fn(),
+      killSession: vi.fn(),
+      listSessions: vi.fn(() => []),
+      getStats: vi.fn(() => ({})),
+    },
+    runSummaryTrackers: new Map(),
+    activePlanOrchestrators: new Map(),
+    scheduledRuns: new Map(),
+    teamWatcher: { getTeams: vi.fn(() => []), hasActiveTeammates: vi.fn(() => false) },
+    tunnelManager: null,
+    pushStore: null,
+    startScheduledRun: vi.fn(),
+    stopScheduledRun: vi.fn(),
+
+    // -- AuthPort --
+    authSessions: null,
+    qrAuthFailures: null,
+    // https already declared above in ConfigPort (shared property)
+
+    // Convenience accessors (not part of any port interface)
+    _session: session,
+    _sessionId: sessionId,
+  };
+}
+
+export type MockRouteContext = ReturnType<typeof createMockRouteContext>;
+```
+
+2. Add to `test/mocks/index.ts` barrel:
+
+```typescript
+export { createMockRouteContext, type MockRouteContext } from './mock-route-context.js';
+```
+
+3. Create `test/routes/` directory for route test files.
+
+4. Create `test/routes/_route-test-utils.ts` with Fastify test helpers:
+
+```typescript
+/**
+ * Shared utilities for route testing.
+ *
+ * Creates minimal Fastify instances with just the route module under test
+ * and a mock context. Uses app.inject() for HTTP testing without real ports.
+ */
+import Fastify, { type FastifyInstance } from 'fastify';
+import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
+
+export interface RouteTestHarness {
+  app: FastifyInstance;
+  ctx: MockRouteContext;
+}
+
+/**
+ * Creates a Fastify instance with a route module registered against a mock context.
+ *
+ * @param registerFn - The route registration function (e.g., registerSessionRoutes).
+ *   Uses `any` for ctx parameter because route functions expect typed port intersections
+ *   that MockRouteContext satisfies structurally but not nominally.
+ * @param ctxOptions - Optional overrides for the mock context
+ */
+export async function createRouteTestHarness(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerFn: (app: FastifyInstance, ctx: any) => void,
+  ctxOptions?: { sessionId?: string },
+): Promise<RouteTestHarness> {
+  const app = Fastify({ logger: false });
+  const ctx = createMockRouteContext(ctxOptions);
+
+  registerFn(app, ctx);
+  await app.ready();
+
+  return { app, ctx };
+}
+```
+
+### Why `ctx: any` in the harness
+
+Route registration functions like `registerSessionRoutes(app, ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort)` expect specific port intersection types. TypeScript won't accept `unknown` here because it's not assignable to the port types. The `MockRouteContext` satisfies the interfaces structurally (it has all the required properties and methods), but since it's not declared as implementing them, we need `any` at the call site. This is the standard pattern for test mocks in TypeScript.
+
+### Verification
+
+```bash
+tsc --noEmit
+```
+
+---
+
+## Task 7: Add session routes tests
+
+**Estimated effort**: 4 hours
+**Depends on**: Task 6
+**Files created**: `test/routes/session-routes.test.ts`
+**Port**: 3220 (only if SSE tests needed; prefer `app.inject()`)
+
+### Coverage targets
+
+`src/web/routes/session-routes.ts` is the largest route module (43 handlers). Focus on the most critical endpoints first:
+
+#### Priority 1: Session CRUD (must test)
+
+| Method | Path | What to test |
+|--------|------|-------------|
+| `GET` | `/api/sessions` | Returns session list; empty when no sessions |
+| `GET` | `/api/sessions/:id` | Returns session state; 404 for unknown ID |
+| `POST` | `/api/sessions` | Creates session; validates workingDir; rejects invalid paths |
+| `DELETE` | `/api/sessions/:id` | Calls cleanupSession; 404 for unknown ID |
+
+#### Priority 2: Session I/O
+
+| Method | Path | What to test |
+|--------|------|-------------|
+| `POST` | `/api/sessions/:id/input` | Sends input to session; validates input length; 404 for unknown |
+| `POST` | `/api/sessions/:id/resize` | Validates cols/rows bounds; 404 for unknown |
+| `GET` | `/api/sessions/:id/buffer` | Returns terminal buffer; 404 for unknown |
+
+#### Priority 3: Session actions
+
+| Method | Path | What to test |
+|--------|------|-------------|
+| `POST` | `/api/sessions/:id/run` | Runs prompt on session |
+| `POST` | `/api/sessions/:id/clear` | Clears session |
+| `POST` | `/api/sessions/:id/compact` | Compacts session |
+| `POST` | `/api/sessions/:id/interactive` | Starts interactive mode |
+| `POST` | `/api/sessions/:id/quick-start` | Quick start flow |
+
+### Test pattern
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+
+describe('session-routes', () => {
+  let harness: RouteTestHarness;
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerSessionRoutes);
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+  });
+
+  describe('GET /api/sessions', () => {
+    it('returns empty array when no sessions', async () => {
+      harness.ctx.sessions.clear();
+      const res = await harness.app.inject({ method: 'GET', url: '/api/sessions' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual([]);
+    });
+
+    it('returns session list with one session', async () => {
+      const res = await harness.app.inject({ method: 'GET', url: '/api/sessions' });
+      expect(res.statusCode).toBe(200);
+      const sessions = JSON.parse(res.body);
+      expect(sessions).toHaveLength(1);
+    });
+  });
+
+  describe('GET /api/sessions/:id', () => {
+    it('returns 404 for unknown session', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/sessions/nonexistent',
+      });
+      expect(res.statusCode).toBe(404);
+    });
+  });
+
+  describe('POST /api/sessions/:id/input', () => {
+    it('rejects input exceeding max length', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/input`,
+        payload: { input: 'x'.repeat(65537) },
+      });
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('POST /api/sessions/:id/resize', () => {
+    it('rejects cols exceeding max', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/resize`,
+        payload: { cols: 501, rows: 24 },
+      });
+      expect(res.statusCode).toBe(400);
+    });
+  });
+});
+```
+
+### Key assertions to include
+
+- **404 for unknown sessions**: Every `:id` endpoint must return 404 for nonexistent IDs
+- **Input validation**: Bad paths, oversized inputs, invalid resize dimensions
+- **Side effects**: Verify `ctx.broadcast()` was called with correct event type after mutations
+- **Response shape**: Verify response bodies match expected API types
+
+### Verification
+
+```bash
+npx vitest run test/routes/session-routes.test.ts
+```
+
+---
+
+## Task 8: Add system + respawn routes tests
+
+**Estimated effort**: 4 hours
+**Depends on**: Task 6
+**Files created**: `test/routes/system-routes.test.ts`, `test/routes/respawn-routes.test.ts`
+
+### System routes (`src/web/routes/system-routes.ts`)
+
+Focus on status and configuration endpoints:
+
+| Method | Path | What to test |
+|--------|------|-------------|
+| `GET` | `/api/status` | Returns server status with uptime, session count |
+| `GET` | `/api/stats` | Returns mux stats |
+| `GET` | `/api/config` | Returns current config |
+| `PUT` | `/api/config` | Updates config; validates input |
+| `GET` | `/api/settings` | Returns user settings |
+| `PUT` | `/api/settings` | Updates settings; validates input |
+| `GET` | `/api/subagents` | Returns subagent list |
+| `GET` | `/api/screenshots` | Returns screenshot list |
+
+### Respawn routes (`src/web/routes/respawn-routes.ts`)
+
+| Method | Path | What to test |
+|--------|------|-------------|
+| `GET` | `/api/sessions/:id/respawn` | Returns respawn status; null when not configured |
+| `POST` | `/api/sessions/:id/respawn/start` | Starts respawn; 404 for unknown session |
+| `POST` | `/api/sessions/:id/respawn/stop` | Stops respawn; 404 for unknown session |
+| `PUT` | `/api/sessions/:id/respawn/config` | Updates respawn config; validates |
+| `POST` | `/api/sessions/:id/respawn/enable` | Enables respawn loop |
+| `POST` | `/api/sessions/:id/respawn/disable` | Disables respawn loop |
+
+### Test patterns
+
+Same pattern as Task 7 — `createRouteTestHarness` with `registerSystemRoutes` / `registerRespawnRoutes`.
+
+For respawn tests, pre-populate `ctx.respawnControllers` with a mock controller in `beforeEach`:
+
+```typescript
+beforeEach(async () => {
+  harness = await createRouteTestHarness(registerRespawnRoutes);
+  // Add a mock respawn controller for the default session
+  harness.ctx.respawnControllers.set(harness.ctx._sessionId, {
+    getState: vi.fn(() => 'idle'),
+    getConfig: vi.fn(() => ({})),
+    getStatus: vi.fn(() => ({ state: 'idle', health: 100 })),
+    start: vi.fn(),
+    stop: vi.fn(),
+    updateConfig: vi.fn(),
+    enable: vi.fn(),
+    disable: vi.fn(),
+  });
+});
+```
+
+### Verification
+
+```bash
+npx vitest run test/routes/system-routes.test.ts
+npx vitest run test/routes/respawn-routes.test.ts
+```
+
+---
+
+## Task 9: Slim down `respawn-test-utils.ts`
+
+**Estimated effort**: 30 minutes
+**Depends on**: Tasks 4, 5
+**Files modified**: `test/respawn-test-utils.ts`
+
+After Tasks 4–5 are verified passing with shared mocks, slim down `respawn-test-utils.ts` to remove duplicates.
+
+### Steps
+
+1. **Remove** from `respawn-test-utils.ts` what has been moved to shared mocks:
+   - `MockSession` class → now in `test/mocks/mock-session.ts`
+   - `createMockSession()` → now in `test/mocks/mock-session.ts`
+   - `terminalOutputs` → now in `test/mocks/mock-session.ts`
+   - `waitForEvent()` / `createDeferred()` → now in `test/mocks/test-helpers.ts`
+
+2. **Keep** respawn-specific utilities that don't belong in the general mocks:
+   - `TimeController` / `createTimeController()` — respawn-specific timer control
+   - `MockAiIdleChecker` / `MockAiPlanChecker` — respawn-specific AI mocks
+   - `createStateTracker()` / `createEventRecorder()` — respawn state tracking
+   - `FAST_TEST_CONFIG` / `AI_ENABLED_TEST_CONFIG` — respawn config presets
+   - `waitForState()` — respawn state machine waiter
+
+3. **Update imports** in `respawn-test-utils.ts` to re-use shared mocks:
+   ```typescript
+   import { MockSession, createMockSession, terminalOutputs } from './mocks/index.js';
+   import { waitForEvent, createDeferred } from './mocks/index.js';
+   export { MockSession, createMockSession, terminalOutputs, waitForEvent, createDeferred };
+   ```
+
+This preserves backward compatibility for any future tests that import from `respawn-test-utils.ts` directly while eliminating the duplication.
+
+### Verification
+
+```bash
+tsc --noEmit
+npx vitest run test/respawn-controller.test.ts
+npx vitest run test/respawn-team-awareness.test.ts
+```
+
+---
+
+## What is NOT in scope (and why)
+
+### Migrating `session-manager.test.ts` and `ralph-loop.test.ts` mocks
+
+Both files define mocks inside `vi.mock()` factories that replace entire modules:
+
+```typescript
+// session-manager.test.ts — mock replaces ../src/session.js
+vi.mock('../src/session.js', () => {
+  class MockSession extends EventEmitter { ... }
+  return { Session: MockSession };
+});
+
+// ralph-loop.test.ts — mock replaces ../src/state-store.js
+vi.mock('../src/state-store.js', () => {
+  class MockStateStore { ... }
+  return { getStore: vi.fn(() => instance), StateStore: MockStateStore };
+});
+```
+
+These are fundamentally different from the direct-instantiation pattern:
+- The `vi.mock()` factory runs in an isolated scope — outer imports are not available
+- The mock class must be returned with the exact export names (`Session`, `getStore`, `StateStore`)
+- The `session-manager.test.ts` MockSession auto-registers into a shared `mockState.sessions` Map (tight coupling with test setup)
+
+Migrating would require `vi.hoisted()` to share the class between factory and test scope, plus restructuring the test's module-mocking setup. This is high-complexity, high-risk refactoring with limited benefit since these tests already work. The shared `MockStateStore` in `test/mocks/` is available for **new** tests (like route tests) that use direct instantiation instead.
+
+### Full integration tests with real Fastify server
+
+Route tests use `app.inject()` which simulates HTTP without opening ports. Full integration tests that spin up `WebServer`, create real sessions, and stream SSE would be valuable but are a separate effort requiring:
+- A test WebServer factory
+- Session lifecycle management in tests
+- SSE client test utilities
+- Significantly more setup/teardown complexity
+
+### Testing auth middleware in route tests
+
+Route tests bypass authentication (no auth middleware registered on the test Fastify instance). Auth middleware has its own dedicated tests in `auth-security.test.ts` and `qr-auth.test.ts`. Testing auth + routes together is a future integration test concern.
+
+### Testing SSE event streaming
+
+SSE integration requires a running server with `EventSource` client. This is significantly more complex than `app.inject()` tests and is deferred. The existing `sse-events.test.ts` covers SSE patterns.
+
+### Complete route coverage for all 12 modules
+
+This phase covers the 3 highest-value route modules (session, system, respawn — 98 of 162 handlers). The remaining 9 modules (ralph, plan, push, team, mux, file, scheduled, hook-event, case) should be added incrementally in follow-up work.
+
+---
+
+## Summary
+
+| Metric | Before | After |
+|--------|--------|-------|
+| MockSession definitions | 4 (across 4 files) | 1 shared (2 vi.mock() copies remain, intentionally) |
+| MockStateStore definitions | 2 (across 2 files) | 1 shared (2 vi.mock() copies remain, intentionally) |
+| Files importing from `respawn-test-utils.ts` | 0 | Utilities split into `test/mocks/` |
+| Route test files | 0 | 3 (session, system, respawn) |
+| Route handlers with dedicated tests | 0 | ~30 (highest-priority endpoints) |
+| Shared mock directory | None | `test/mocks/` with 5 files + barrel |
+
+### Final verification checklist
+
+```bash
+# Type checking
+tsc --noEmit
+
+# Linting
+npm run lint
+
+# Formatting
+npm run format:check
+
+# Run all affected tests individually
+npx vitest run test/respawn-controller.test.ts
+npx vitest run test/respawn-team-awareness.test.ts
+npx vitest run test/routes/session-routes.test.ts
+npx vitest run test/routes/system-routes.test.ts
+npx vitest run test/routes/respawn-routes.test.ts
+
+# Verify unchanged tests still pass
+npx vitest run test/session-manager.test.ts
+npx vitest run test/ralph-loop.test.ts
+
+# Dev server still starts
+npx tsx src/index.ts web --port 3099 &
+curl -s http://localhost:3099/api/status | jq .status  # "ok"
+kill %1
+```

docs/cron-build-brief.md

@@ -0,0 +1,588 @@
+# Claude Code Build Brief: Add Scheduling to Codeman
+
+## 0. Purpose of This Brief
+
+You are Claude Code working inside the Codeman repository.
+
+Your task is to add a **small, reliable scheduling layer** to Codeman while preserving Codeman's existing architecture and session-management behavior.
+
+This is not a greenfield rewrite. This is not a full product rebuild. This is a focused extension.
+
+The target user wants Codeman-like tmux/web/session management, but with first-class scheduled jobs for Claude, Codex, OpenCode, Terminal, or any other configurable coding-agent harness.
+
+---
+
+## 1. Non-Negotiable Goal
+
+Add scheduling to Codeman so a user can define a scheduled coding-agent job that:
+
+1. Has a name.
+2. Uses an existing Codeman-supported agent/session type where possible.
+3. Has a working directory.
+4. Has a prompt or prompt file.
+5. Has a schedule.
+6. Can be enabled or disabled.
+7. Can be manually run now.
+8. When due, creates a Codeman/tmux session.
+9. Sends the configured prompt into that session.
+10. Records last run, next run, status, and run history.
+
+The first working version should prioritize **scheduling correctness and reuse of Codeman's existing tmux/session system** over UI polish.
+
+---
+
+## 2. Core Architectural Rule
+
+Do **not** rebuild Codeman's session layer.
+
+Reuse existing Codeman functionality for:
+
+- Creating sessions.
+- Naming sessions.
+- Launching Claude/Codex/OpenCode/Terminal sessions.
+- Sending input into sessions.
+- Displaying sessions in the web UI.
+- Killing sessions.
+- Tracking session status if already supported.
+
+If an internal API/service/function already exists, reuse it.
+
+If no reusable function exists, create a thin wrapper around the existing implementation rather than duplicating logic.
+
+---
+
+## 3. Product Boundary
+
+This build is **Codeman + Scheduler**.
+
+It is not yet:
+
+- A full quota engine.
+- A full lock manager.
+- A replacement for Codeman's terminal UI.
+- A new FastAPI application.
+- A multi-tenant SaaS platform.
+- A complex cron-management product.
+- A full agent autonomy framework.
+
+Keep the build small and shippable.
+
+---
+
+## 4. Required Working Scope for v0.1
+
+Implement the following minimum features.
+
+### 4.1 Scheduled Jobs List
+
+Create a UI page showing all scheduled jobs.
+
+Each row/card should show:
+
+- Job name.
+- Agent/session type.
+- Working directory.
+- Schedule type.
+- Enabled/disabled state.
+- Last run time.
+- Next run time.
+- Last run status.
+- Actions:
+  - Run Now.
+  - Enable/Disable.
+  - Edit.
+  - Delete.
+
+### 4.2 Create/Edit Scheduled Job
+
+Create a form for scheduled jobs with these fields:
+
+- `name`
+- `agent_type`
+  - Reuse Codeman's existing session/agent types where possible.
+  - Include at least Terminal/custom command if supported.
+- `working_directory`
+- `launch_command` if needed by Codeman's model.
+- `prompt_mode`
+  - `inline_text`
+  - `prompt_file_path`
+- `prompt_text`
+- `prompt_file_path`
+- `input_mode`
+  - `paste`
+  - `typed`
+- `schedule_type`
+  - `once`
+  - `interval_minutes`
+  - `daily_time`
+  - `weekly_time`
+- `run_at` for one-time jobs.
+- `interval_minutes` for interval jobs.
+- `daily_time` for daily jobs.
+- `weekly_days` and `weekly_time` for weekly jobs.
+- `enabled`
+- `notes` optional.
+
+Do not build a complex visual cron editor in v0.1.
+
+### 4.3 Run Now
+
+Every scheduled job must support a `Run Now` action.
+
+Run Now should:
+
+1. Create a new session through Codeman's existing session creation logic.
+2. Send the configured prompt into the session using Codeman's existing input mechanism.
+3. Create a run-history record.
+4. Update last-run fields.
+5. Redirect or link the user to the created Codeman session.
+
+### 4.4 Background Scheduler Loop
+
+Add a small background scheduler loop that runs inside the Codeman backend process.
+
+The loop should:
+
+1. Wake every 15-60 seconds.
+2. Load enabled schedules.
+3. Find schedules where `next_run_at <= now`.
+4. Create a scheduled run.
+5. Launch the session using existing Codeman session logic.
+6. Send the prompt.
+7. Record run history.
+8. Compute the next run time.
+9. Avoid duplicate launches if the loop overlaps or restarts.
+
+Keep this simple and robust.
+
+### 4.5 Run History
+
+Every scheduled execution should create a run-history record.
+
+Track:
+
+- `id`
+- `scheduled_job_id`
+- `session_id` or Codeman session reference.
+- `session_name` if applicable.
+- `started_at`
+- `finished_at` optional.
+- `status`
+  - `created`
+  - `session_started`
+  - `prompt_sent`
+  - `failed`
+- `error_message` optional.
+- `trigger_type`
+  - `scheduled`
+  - `manual_run_now`
+- `created_session_url` or route reference if easy.
+
+---
+
+## 5. Scheduling Rules
+
+### 5.1 Once
+
+Run at a specific date/time.
+
+After successful launch:
+
+- Set `enabled = false`, or mark as completed.
+
+### 5.2 Interval
+
+Run every N minutes.
+
+Example:
+
+- Every 60 minutes.
+- Every 240 minutes.
+
+After launch:
+
+- `next_run_at = now + interval_minutes`.
+
+### 5.3 Daily
+
+Run every day at HH:MM.
+
+After launch:
+
+- Compute the next occurrence of HH:MM after now.
+
+### 5.4 Weekly
+
+Run on selected weekdays at HH:MM.
+
+After launch:
+
+- Compute the next selected weekday/time after now.
+
+### 5.5 Timezone
+
+Use the server's local timezone for v0.1 unless Codeman already has timezone handling.
+
+Add a visible note in the UI:
+
+> Times use the server's local timezone.
+
+Do not overbuild timezone support in v0.1.
+
+---
+
+## 6. Data Storage Decision
+
+First inspect Codeman's existing persistence model.
+
+If Codeman already has a database or persistence layer:
+
+- Reuse it.
+- Add scheduled job and scheduled run models/tables/records using the existing pattern.
+
+If Codeman uses files or JSON state:
+
+- Use the same style for v0.1.
+- Prefer simple persistence over introducing a heavy new dependency.
+
+If there is no appropriate persistence layer:
+
+- Add SQLite only if it fits the codebase cleanly.
+- Otherwise use a JSON file store for the first version.
+
+Do not introduce Postgres, Redis, Celery, or a separate scheduler service.
+
+---
+
+## 7. Concurrency and Duplicate-Run Guard
+
+Implement a basic duplicate-run guard.
+
+A schedule should not launch twice for the same due time.
+
+Minimum acceptable approach:
+
+- Before launching, create/update a run record with a `created` or `launching` state.
+- Use a schedule-level `last_triggered_at` or `last_due_key` to avoid double launching.
+- If launch fails, record failure clearly.
+
+Do not build distributed locks. Codeman is expected to be local/single-instance for v0.1.
+
+---
+
+## 8. Multi-Session Warning
+
+When the user clicks `Run Now`, show a warning if there are already active sessions for the same agent type.
+
+Minimum behavior:
+
+- If active sessions exist, show a confirmation warning.
+- User can continue anyway.
+
+For scheduled automatic runs:
+
+- Add a setting on the scheduled job:
+  - `warn_only`
+  - `skip_if_same_agent_running`
+
+Default:
+
+- `warn_only` for manual runs.
+- `skip_if_same_agent_running = false` for automatic runs unless easy to implement.
+
+Do not build a complete quota engine in v0.1.
+
+---
+
+## 9. Prompt Sending Rules
+
+The scheduler must support sending the configured prompt into the created session.
+
+Prompt source:
+
+1. Inline prompt text.
+2. Prompt file path.
+
+Input mode:
+
+1. Paste mode.
+2. Typed mode.
+
+If only one input mode is easy with Codeman's current internals, implement that first and structure the code so the other can be added later.
+
+Important:
+
+- Do not send prompts to a session if session creation failed.
+- Record prompt-send success/failure in run history.
+- Save enough metadata to understand what prompt was used.
+
+---
+
+## 10. UI Bifurcation
+
+Keep UI changes cleanly separated.
+
+Add scheduler UI under a clear navigation item:
+
+- `Scheduled Jobs`
+
+Do not clutter the existing session dashboard.
+
+The existing session dashboard may show sessions created by scheduled jobs, but the scheduling controls should live in their own section.
+
+Recommended pages/routes:
+
+- `/schedules`
+- `/schedules/new`
+- `/schedules/:id`
+- `/schedules/:id/edit`
+- `/schedules/:id/run-now`
+- `/schedules/:id/enable`
+- `/schedules/:id/disable`
+- `/schedules/:id/delete`
+
+Use Codeman's existing frontend conventions and routing style.
+
+---
+
+## 11. Backend Bifurcation
+
+Keep scheduler code separate from existing session code.
+
+Recommended logical modules, adapted to Codeman's actual structure:
+
+- `scheduler/model` or equivalent.
+- `scheduler/store` or equivalent.
+- `scheduler/service` for schedule calculations and launch logic.
+- `scheduler/loop` for the background due-job checker.
+- `scheduler/routes` for API/UI endpoints.
+- `scheduler/time` for next-run calculations.
+
+Do not mix scheduling logic directly into terminal rendering, xterm handling, or low-level tmux code.
+
+The scheduler service should call session services; it should not own tmux directly unless Codeman has no session abstraction.
+
+---
+
+## 12. Required Discovery Phase Before Coding
+
+Before implementing, inspect the Codeman repo and produce a short architecture note in the terminal or in a file called:
+
+`docs/cron-discovery.md`
+
+This note must identify:
+
+1. Where session creation happens.
+2. Where agent/session types are defined.
+3. Where input is sent into a session.
+4. Where active sessions are listed.
+5. Where session kill/delete is handled.
+6. How session state is stored.
+7. Whether there is existing persistence.
+8. Where backend routes live.
+9. Where frontend pages/components live.
+10. The smallest integration points for scheduling.
+
+Do not start coding until this discovery is complete.
+
+---
+
+## 13. Implementation Phases
+
+### Phase 1: Discovery
+
+Deliverable:
+
+- `docs/cron-discovery.md`
+
+Must answer the 10 discovery questions above.
+
+### Phase 2: Data Model / Persistence
+
+Deliverable:
+
+- Scheduled job persistence.
+- Scheduled run history persistence.
+- Basic create/read/update/delete operations.
+
+### Phase 3: Scheduler Calculation Logic
+
+Deliverable:
+
+- Functions to compute `next_run_at` for:
+  - once
+  - interval
+  - daily
+  - weekly
+
+Add tests if the repo has an existing test setup.
+
+### Phase 4: Manual Run Now
+
+Deliverable:
+
+- Create scheduled job.
+- Click Run Now.
+- Codeman session is created.
+- Prompt is sent.
+- Run history is recorded.
+- UI links to the session.
+
+This is the most important milestone.
+
+### Phase 5: Background Scheduler Loop
+
+Deliverable:
+
+- Enabled schedules launch automatically when due.
+- Run history is recorded.
+- `last_run_at` and `next_run_at` update.
+- Duplicate launch guard exists.
+
+### Phase 6: UI Polish Only After Functionality
+
+Deliverable:
+
+- Scheduled jobs list is readable.
+- Create/edit form is usable.
+- Status labels are clear.
+- Errors are visible.
+
+Do not polish before Phase 4 works.
+
+---
+
+## 14. Acceptance Criteria
+
+The build is acceptable when all these pass.
+
+### Manual Run
+
+1. Create a schedule/job with inline prompt.
+2. Click Run Now.
+3. A new Codeman/tmux session starts.
+4. Prompt is sent into that session.
+5. The created session is visible in Codeman's normal session UI.
+6. Run history shows success or failure.
+
+### One-Time Schedule
+
+1. Create a one-time schedule 2 minutes in the future.
+2. Wait for it to become due.
+3. Scheduler launches a session.
+4. Prompt is sent.
+5. Schedule does not repeatedly launch forever.
+
+### Interval Schedule
+
+1. Create interval schedule every 2 minutes.
+2. It launches once when due.
+3. It computes the next due time.
+4. It does not launch duplicates for the same due time.
+
+### Daily Schedule
+
+1. Create daily schedule at a time a few minutes ahead.
+2. It launches when due.
+3. Next run becomes tomorrow at the same time.
+
+### Disable Schedule
+
+1. Disable a schedule.
+2. It does not launch even when due.
+
+### Error Handling
+
+1. Invalid working directory produces visible error.
+2. Invalid prompt file produces visible error.
+3. Failed session launch creates failed run-history entry.
+
+---
+
+## 15. Explicitly Out of Scope for v0.1
+
+Do not implement these unless all required scope is already working:
+
+- Full quota engine.
+- Advanced lock manager.
+- Post-run git inspection reports.
+- Complex recurring calendar UI.
+- User accounts / RBAC.
+- External distributed workers.
+- Redis.
+- Postgres.
+- Celery.
+- Kubernetes.
+- A separate Python service.
+- Full visual cron editor.
+- AI-generated follow-up prompts.
+- Automatic continuation after idle.
+- Any attempt to bypass agent quotas or platform limits.
+
+---
+
+## 16. Quality Rules
+
+Follow these rules while coding:
+
+1. Reuse existing Codeman services and conventions.
+2. Keep scheduler code isolated.
+3. Prefer boring, readable code over clever abstractions.
+4. Add error messages that a human can understand.
+5. Do not break existing Codeman sessions.
+6. Do not rename existing core concepts unnecessarily.
+7. Do not introduce large dependencies without strong reason.
+8. Keep v0.1 local-first and single-instance.
+9. Commit in logical chunks if git is available.
+10. After coding, provide a final implementation summary.
+
+---
+
+## 17. Final Response Required from Claude Code
+
+At the end, report:
+
+1. Files changed.
+2. New routes/pages added.
+3. New data structures added.
+4. How the scheduler loop works.
+5. How to run the app.
+6. How to test manual Run Now.
+7. How to test scheduled execution.
+8. Known limitations.
+9. Suggested v0.2 improvements.
+
+---
+
+## 18. v0.2 Ideas, Not for Current Build
+
+Keep these in mind but do not build unless v0.1 is complete:
+
+- Quota-aware scheduling.
+- Manual takeover locks.
+- Post-idle inspection.
+- Git diff reports.
+- Schedule groups.
+- Prompt templates.
+- Agent-specific concurrency rules.
+- Better timezone support.
+- Audit events.
+- More advanced cron expressions.
+
+---
+
+## 19. Final Reminder
+
+The goal is to add **scheduling** to Codeman quickly and cleanly.
+
+Do not drift into building a new platform.
+
+The highest-priority path is:
+
+1. Discover existing Codeman integration points.
+2. Add scheduled job persistence.
+3. Add Run Now.
+4. Add background due-job loop.
+5. Add minimal UI.
+6. Verify that scheduled jobs create real Codeman/tmux sessions and send prompts.
+

docs/cron-discovery.md

@@ -0,0 +1,142 @@
+# CRON_DISCOVERY.md
+
+Phase 1 deliverable for the "Add Scheduling to Codeman" build brief.
+This documents the existing Codeman architecture and the smallest integration
+points for a cron. **No session/tmux logic will be rebuilt** —
+the new code is purely a trigger + persistence + history layer on top of the
+existing primitives.
+
+Stack: `aicodeman` v1.2.1 — Fastify 5 backend, `node-pty` + tmux sessions,
+vanilla-JS SPA frontend served as static assets, JSON file state store, zod
+validation, ports-based dependency injection.
+
+---
+
+## 0. Critical finding: an existing `ScheduledRun` is NOT a cron
+
+Codeman already has a `ScheduledRun` concept (`/api/scheduled`,
+`src/web/ports/infra-port.ts:14-26`, `src/web/server.ts:1480-1605`). It is a
+**run-now, duration-bounded autonomous loop**: given `{prompt, workingDir,
+durationMinutes}` it immediately spawns/kills throwaway sessions in a loop until
+the duration elapses. It has **no** time-based triggering, recurrence
+(once/interval/daily/weekly), enable/disable, next-run calculation, run history,
+or persistence across restarts.
+
+Therefore the brief's core (the calendar/cron trigger layer) does **not** exist
+and must be built. The execution primitives it sits on top of **do** exist and
+will be reused. To honor brief §16 ("do not rename existing core concepts"), the
+new feature is named **`CronJob`** (with **`CronJobRun`** history
+records), kept distinct from the existing `ScheduledRun`.
+
+---
+
+## 1. Where session creation happens
+
+- Canonical create flow: `POST /api/sessions`,
+  `src/web/routes/session-routes.ts:262-438`.
+  - `new Session({ workingDir, mode, ... })` (`src/session.ts:421-570`)
+  - `ctx.addSession(session)` → `ctx.setupSessionListeners(session)` →
+    `ctx.persistSessionState(session)` (all via `SessionPort`).
+- `SessionPort` interface: `src/web/ports/session-port.ts:8-16`.
+- **Integration point:** the cron service will mirror this exact sequence
+  (create → addSession → setupSessionListeners → start) via `SessionPort`,
+  not reimplement it.
+
+## 2. Where agent/session types are defined
+
+- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`
+  (`src/types/session.ts:43-44`). `shell` covers the brief's "Terminal/custom".
+- CLI availability resolvers in `src/utils/{claude,codex,gemini,opencode}-cli-resolver.ts`.
+- **Integration point:** the job's `agentType` reuses `SessionMode` verbatim.
+
+## 3. Where input is sent into a session
+
+- Raw / paste: `session.write(data)` (`src/session.ts:2243-2247`) — direct PTY write.
+- Typed (recommended): `session.writeViaMux(data)` (`src/session.ts:2301-2311`)
+  — tmux `send-keys`, falls back to PTY. Submit requires trailing `\r`.
+- **Integration point:** prompt delivery uses `writeViaMux` (typed) by default,
+  `write` (paste) as the alternate `input_mode`.
+
+## 4. Where active sessions are listed
+
+- `ctx.sessions: ReadonlyMap<string, Session>` (`SessionPort`).
+- Filters: `Array.from(ctx.sessions.values()).filter(s => s.mode === X)` and
+  `.isBusy()` / `.isIdle()` (`src/session-manager.ts:220-247`).
+- **Integration point:** the §8 multi-session warning queries this map.
+
+## 5. Where session kill/delete is handled
+
+- `ctx.cleanupSession(sessionId, killMux?, reason?)`
+  (`SessionPort`; impl `src/web/server.ts:997-1152`). Underlying
+  `session.stop(killMux)` at `src/session.ts:2498-2585`.
+- The cron does **not** kill sessions it launches (the brief wants them
+  visible in the normal session UI); cleanup stays user-driven.
+  _Superseded post-review:_ recurring jobs now default to
+  `autoClosePreviousSession: true` — the previous run's still-open session is
+  closed via `cleanupSession` when the next run fires (see
+  `docs/cron-guide.md` §8); opt out per job for fully user-driven cleanup.
+
+## 6. How session state is stored / 7. Existing persistence
+
+- JSON file store: `~/.codeman/state.json` (+ `state-inner.json` for Ralph).
+  `StateStore` class `src/state-store.ts:71`; `AppState` interface
+  `src/types/app-state.ts:99-114`.
+- Pattern: declare a field on `AppState`, add typed get/set methods on
+  `StateStore` that mutate in-memory state and call the debounced `save()`
+  (500ms debounce, atomic temp-file+rename, `.bak` backup, circuit breaker).
+- **Integration point:** add `cronJobs?: Record<string, CronJob>` and
+  `cronJobRuns?: Record<string, CronJobRun>` to `AppState`, with
+  matching `StateStore` accessors. No new DB (brief §6 forbids Postgres/Redis).
+
+## 8. Where backend routes live
+
+- Route modules: `src/web/routes/*.ts`; barrel `src/web/routes/index.ts`;
+  registered in `WebServer.setupRoutes()` `src/web/server.ts:858-876` with a
+  single `ctx` object from `createRouteContext()` (`src/web/server.ts:553-613`)
+  that satisfies all port interfaces.
+- Validation: zod schemas in `src/web/schemas.ts`, applied via
+  `parseBody(Schema, req.body)` (`src/web/route-helpers.ts:101-111`).
+- Errors: `createErrorResponse(ApiErrorCode.X, msg)` / `ApiResponse`
+  (`src/types/api.ts`), auto-mapped to HTTP status by a `preSerialization` hook
+  (`src/web/server.ts:644-659`).
+- SSE: `ctx.broadcast(SseEvent.X, data)` (`EventPort`,
+  `src/web/sse-events.ts`); frontend mirror in `src/web/public/constants.js`.
+- **Integration point:** new `cron-routes.ts` registered alongside the
+  others; new zod schema; new `SseEvent` constants for job list/run changes.
+
+## 9. Where frontend pages/components live
+
+- Vanilla-JS SPA: single `src/web/public/index.html` + feature mixin files
+  (`Object.assign(CodemanApp.prototype, {...})`). API via `api-client.js`
+  (`_apiJson/_apiPost/_apiDelete`). Build = esbuild minify + content-hash, no
+  bundler (`scripts/build.mjs`).
+- UI is panels/modals toggled by JS classes; forms use `.form-row` / `.modal`
+  conventions (`styles.css`). SSE handler map in `app.js`.
+- **Integration point:** add a new `cron-ui.js` mixin + a panel/modal in
+  `index.html` + nav entry, following the orchestrator/respawn panel pattern.
+
+## 10. Background-loop pattern (for the due-checker)
+
+- Established pattern: `this.cleanup.setInterval(fn, intervalMs, {description})`
+  in `WebServer.start()` (`src/web/server.ts:~1942-1966`), auto-disposed in
+  `WebServer.stop()` via `this.cleanup.dispose()` (`src/web/server.ts:2336`).
+  RalphLoop (`src/ralph-loop.ts:268-286`) shows the self-rescheduling guard idiom.
+- **Integration point:** register a 30s cron tick via `cleanup.setInterval`;
+  no manual shutdown wiring needed.
+
+---
+
+## Smallest integration points (summary)
+
+| New piece | Reuses | Location |
+| --- | --- | --- |
+| `CronJob` / `CronJobRun` types | — (new) | `src/types/cron.ts` |
+| Persistence | `StateStore` / `AppState` | `src/types/app-state.ts`, `src/state-store.ts` |
+| Next-run time math | — (new, pure, unit-tested) | `src/cron/cron-time.ts` |
+| Launch + send prompt | `SessionPort` (`addSession`/listeners/`writeViaMux`) | `src/cron/cron-service.ts` |
+| Background due loop | `cleanup.setInterval` pattern | `src/cron/cron-loop.ts` |
+| Routes + schema | route/ports/zod/SSE patterns | `src/web/routes/cron-routes.ts`, `src/web/schemas.ts`, `src/web/sse-events.ts` |
+| UI | panel/modal/mixin conventions | `src/web/public/cron-ui.js`, `index.html` |
+
+Nothing in the session, tmux, persistence, routing, or SSE subsystems is
+rewritten — the cron is additive and calls existing services.

docs/cron-guide.md

@@ -0,0 +1,426 @@
+# Cron Jobs — User & Operator Guide
+
+Codeman's **Cron** feature lets you save named, recurring jobs that automatically
+spin up a Claude (or shell / OpenCode / Codex / Gemini) session on a schedule and
+feed it a prompt. Think "cron for agent sessions": _"every weekday at 3am, open a
+Claude session in `~/proj` and tell it to update dependencies and open a PR."_
+
+- **UI**: the **⏰ Cron** button in the header → the Cron Jobs modal (`#cronModal`).
+- **API**: `/api/cron/jobs*` and `/api/cron/runs`.
+- **Code**: `src/cron/cron-service.ts`, `src/cron/cron-time.ts`, `src/cron/cron-input.ts`,
+  types in `src/types/cron.ts`, routes in `src/web/routes/cron-routes.ts`,
+  frontend in `src/web/public/cron-ui.js`.
+
+> **Not to be confused with `ScheduledRun` (`/api/scheduled`).** That older,
+> deliberately-separate concept is a _run-now, duration-bounded autonomous loop_
+> (`{prompt, workingDir, durationMinutes}` → spawn/kill throwaway sessions until
+> the duration elapses). It has no recurrence, no saved jobs, and no next-run
+> calculation. The two systems never interact. This guide is only about **Cron
+> jobs** (`Cron*`). See `docs/cron-discovery.md` §0.
+
+---
+
+## 1. Quick start
+
+### In the browser
+
+1. Click **⏰ Cron** in the header.
+2. Click **+ New Job**.
+3. Fill in a **name**, pick an **agent type** and **working directory**, choose a
+   **prompt** (inline text or a file path), pick a **schedule**, and leave
+   **Enabled** on.
+4. **Save**. The job appears in the list with its computed **next run**.
+5. Use **Run Now** to fire it immediately without waiting for the schedule.
+
+### With curl
+
+```bash
+API=http://localhost:3000
+
+# Create a daily job (03:00 server-local time)
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "nightly-deps",
+    "agentType": "claude",
+    "workingDir": "/home/me/proj",
+    "promptMode": "inline_text",
+    "promptText": "Update dependencies and open a PR",
+    "inputMode": "typed",
+    "scheduleType": "daily",
+    "dailyTime": "03:00",
+    "enabled": true,
+    "concurrencyPolicy": "warn_only"
+  }' | jq
+
+# List jobs
+curl -s "$API/api/cron/jobs" | jq
+
+# Run one immediately
+curl -s -X POST "$API/api/cron/jobs/<jobId>/run" | jq
+
+# See a job's run history
+curl -s "$API/api/cron/jobs/<jobId>/runs" | jq
+```
+
+---
+
+## 2. Concepts
+
+| Term                       | Meaning                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Cron job** (`CronJob`)   | A saved, named definition: what agent to launch, where, with what prompt, on what schedule.      |
+| **Run** (`CronJobRun`)     | One execution of a job — a history record with a status and a link to the session it created.    |
+| **Schedule type**          | How fire times are computed: `once`, `interval`, `daily`, or `weekly`.                           |
+| **Next run** (`nextRunAt`) | Server-computed epoch-ms of the next fire. `null` when the job is disabled or has no future run. |
+| **Due tick**               | A background loop (every 30s) that launches any enabled job whose `nextRunAt` has passed.        |
+
+A job is essentially a **trigger + persistence + history layer on top of the
+existing session primitives**. When a job fires, the cron service does exactly
+what the "quick start" route does — `new Session(...)` → `addSession` →
+`setupSessionListeners` → `startInteractive()`/`startShell()` → deliver the
+prompt. It does **not** reimplement any tmux/PTY logic.
+
+---
+
+## 3. The job form — every field
+
+These map 1:1 to `CronJobSchema` (`src/web/schemas.ts`) and the `CronJob` type
+(`src/types/cron.ts`).
+
+| Field                      | Required    | Values / limits                                          | Notes                                                                                                                                                                                      |
+| -------------------------- | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                     | ✅          | 1–200 chars                                              | Display name; also used as the created session's name.                                                                                                                                     |
+| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal.                                                                                                                                |
+| `workingDir`               | ✅          | valid path (allowlist-validated)                         | Validated at **create/update** (must exist, be a directory, and not resolve into a blocked tree — `/etc`, `/root`, `/proc`, `/sys`, `/dev`, or `/` itself) and again **at fire time**.     |
+| `launchCommand`            | —           | ≤ 2000 chars, single line                                | `shell` mode only: sent as the **first input line** once the shell is up, before the prompt. Ignored for other agent types.                                                                |
+| `promptMode`               | ✅          | `inline_text` \| `prompt_file_path`                      | See §5.                                                                                                                                                                                    |
+| `promptText`               | conditional | ≤ 100000 chars, **single line**                          | Required when `promptMode = inline_text`. Newlines are rejected (see §6).                                                                                                                  |
+| `promptFilePath`           | conditional | valid path                                               | Required when `promptMode = prompt_file_path`. Confined to `workingDir` (see §5).                                                                                                          |
+| `inputMode`                | ✅          | `paste` \| `typed`                                       | How the prompt is delivered. See §6.                                                                                                                                                       |
+| `scheduleType`             | ✅          | `once` \| `interval` \| `daily` \| `weekly`              | See §4.                                                                                                                                                                                    |
+| `runAt`                    | conditional | epoch-ms (positive int)                                  | Required for `once`.                                                                                                                                                                       |
+| `intervalMinutes`          | conditional | 1–525600 (≤ 1 year)                                      | Required for `interval`.                                                                                                                                                                   |
+| `dailyTime`                | conditional | `HH:MM` (24h)                                            | Required for `daily`. Server-local time.                                                                                                                                                   |
+| `weeklyDays`               | conditional | array of 1–7 ints, each 0–6 (0 = Sunday)                 | Required for `weekly`.                                                                                                                                                                     |
+| `weeklyTime`               | conditional | `HH:MM` (24h)                                            | Required for `weekly`. Server-local time.                                                                                                                                                  |
+| `enabled`                  | ✅          | boolean                                                  | Disabled jobs never auto-fire (but **Run Now** still works).                                                                                                                               |
+| `notes`                    | —           | ≤ 2000 chars                                             | Free-form.                                                                                                                                                                                 |
+| `concurrencyPolicy`        | ✅          | `warn_only` \| `skip_if_same_agent_running`              | Applies to **automatic** runs only. See §7.                                                                                                                                                |
+| `autoClosePreviousSession` | —           | boolean (default **true**)                               | Recurring schedules only (ignored for `once`): when the next run fires, the still-open session created by this job's **previous** run is closed first via the normal cleanup path. See §8. |
+
+**Cross-field validation** (`refineCronJob` in `schemas.ts`): the conditional
+fields above are enforced by a Zod `superRefine` on create. A missing dependent
+field (e.g. `scheduleType: "once"` with no `runAt`) is rejected with
+`INVALID_INPUT` and a field-specific message.
+
+> ⚠️ **Update caveat.** `PUT /api/cron/jobs/:id` uses a `.partial()` schema that
+> does **not** re-run the cross-field `superRefine`. To keep partial edits safe,
+> `updateJob()` re-validates the **merged** job against the full `CronJobSchema`
+> and throws `400` if the result is inconsistent (e.g. switching to `once`
+> without a `runAt`). So the store is never left with a half-valid job.
+
+---
+
+## 4. Schedule types
+
+Next-run math lives in `src/cron/cron-time.ts` (pure, unit-tested in
+`test/cron-time.test.ts`). **All wall-clock times use the server's local
+timezone** (v0.1 decision).
+
+### `once`
+
+- Fires a single time at the absolute `runAt` epoch-ms.
+- A **missed** one-time job (server was down at `runAt`) **still fires once** on
+  the next tick — `computeNextRunAt` returns `runAt` even if it's in the past,
+  until the job has fired.
+- After firing, the job **self-disables**: `completedOnce = true`, `enabled =
+false`, `nextRunAt = null`.
+
+### `interval`
+
+- Fires every `intervalMinutes`, computed as `fireTime + intervalMinutes`.
+- ⚠️ **Drift**: the next run re-anchors to the actual fire time, not to an ideal
+  cadence — a slow tick or restart shifts subsequent runs slightly later. This is
+  an accepted limitation.
+
+### `daily`
+
+- Fires at `dailyTime` (`HH:MM`) every day, server-local.
+- If today's time has already passed, the next run is tomorrow at that time.
+
+### `weekly`
+
+- Fires at `weeklyTime` on each weekday in `weeklyDays` (0 = Sunday … 6 =
+  Saturday), server-local.
+- The next run is the soonest upcoming matching weekday/time within the next 7
+  days.
+
+---
+
+## 5. Prompt source (`promptMode`)
+
+### `inline_text`
+
+The prompt is the literal `promptText`. Simplest option.
+
+### `prompt_file_path`
+
+The prompt is read from a file at fire time. **This path is security-hardened**
+because a job config is attacker-controllable and the file's contents are
+injected into an agent session (an exfiltration sink over SSE/terminal).
+`resolveSafePromptPath()` enforces, in order:
+
+1. **`realpath` resolution** — symlinks are resolved to their true target, for
+   the prompt file **and for `workingDir` itself**.
+2. **`workingDir` is not a trust boundary** — because it is user-supplied, the
+   resolved `workingDir` is itself rejected if it is `/` or resolves into a
+   blocked tree (`/etc`, `/root`, operator extras) or a pseudo-filesystem
+   (`/proc`, `/sys`, `/dev`). This closes the `workingDir: '/proc'` +
+   `promptFilePath: '/proc/self/environ'` env-exfil trick. The same rule is
+   enforced earlier, at job create/update.
+3. **Blocklist** (defense-in-depth) — sensitive trees (`/etc`, `/root`,
+   `/proc`, `/sys`, `/dev`, known secret locations) are rejected for the
+   resolved prompt file.
+4. **Allowlist (primary gate)** — the resolved path **must live inside the job's
+   (resolved) `workingDir`** (`validateSessionFilePath`). A symlink escaping the
+   workspace fails here.
+5. **Regular-file check** — directories, FIFOs, and `/dev/*` character devices
+   are rejected (they would hang or OOM an unbounded read).
+6. **Size cap** — files larger than **1 MiB** (`MAX_PROMPT_FILE_BYTES`) are
+   rejected.
+7. **Single-line check** — after trailing newlines are stripped, the file
+   content must be a single line (see §6).
+
+If any check fails, the run is recorded as **`failed`** with the reason; no
+session is created.
+
+---
+
+## 6. Prompt delivery (`inputMode`)
+
+Once the CLI is ready (see §8), the prompt is written to the session with a
+trailing carriage return:
+
+| Mode    | Mechanism                                                       | Use when                                         |
+| ------- | --------------------------------------------------------------- | ------------------------------------------------ |
+| `typed` | `session.writeViaMux()` — tmux `send-keys -l` (literal) + Enter | Default; behaves like a human typing the prompt. |
+| `paste` | `session.write()` — writes directly to the PTY/mux              | Bulk paste-style delivery.                       |
+
+> ⚠️ **Single-line only — enforced.** Like all programmatic input in Codeman,
+> multi-line delivery would be silently corrupted (Ink-based TUIs treat a
+> newline as submit; typed mode fuses lines). So newlines are **rejected**: the
+> schema and the form refuse a multi-line `promptText`, and at fire time a
+> prompt file whose content is multi-line (after stripping trailing newlines)
+> fails the run with a clear `errorMessage`. Put multi-line instructions in a
+> file the agent is told to read itself (e.g. "read TASKS.md and do it").
+
+---
+
+## 7. Concurrency policy (automatic runs)
+
+`concurrencyPolicy` governs what happens when a **scheduled** run is due and
+sessions of the same `agentType` already exist:
+
+| Policy                       | Behavior                                                                                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `warn_only`                  | Always launch. (The count is surfaced but not blocking.)                                                                                                                 |
+| `skip_if_same_agent_running` | If ≥ 1 **other, live** session of that mode is active, **skip** this fire — record a `skipped` run and (for recurring schedules) advance the schedule without launching. |
+
+Notes on `skip_if_same_agent_running`:
+
+- Only **live** sessions block: a tab whose CLI already exited (status
+  `stopped`/`error`) does not count.
+- Sessions created by **this job's own previous runs never block it** —
+  otherwise a recurring job would deadlock on the session it created last time
+  and fire exactly once.
+- A skipped **`once`** job is **not consumed**: it stays armed and retries on
+  the next tick until the blocking session goes away, then fires its single run.
+- A skip is **not** a run: it sets `lastStatus = 'skipped'` but does **not**
+  advance `lastRunAt`.
+- Consecutive skips are **coalesced** — a perpetually-skipped interval job writes
+  **one** skip record per streak, not one every tick, so it can't bloat
+  `state.json`.
+
+**Run Now ignores this policy on the server.** The browser shows a `confirm()`
+warning if same-type sessions are active, but if you proceed (or call the API
+directly), the job launches unconditionally.
+
+---
+
+## 8. What happens when a job fires
+
+Sequence in `CronService.launch()`:
+
+1. A `CronJobRun` is created with status **`created`** and broadcast
+   (`cron:runCreated`).
+2. The prompt is resolved (inline or file, single-line enforced). Failure →
+   **`failed`**.
+3. `workingDir` is checked (`statSync().isDirectory()`). Missing/not-a-dir →
+   **`failed`**.
+4. **Auto-close previous session** (recurring schedules, unless
+   `autoClosePreviousSession: false`): any still-open session created by this
+   job's previous runs is closed via the normal session-cleanup path.
+5. The global session cap is checked (`MAX_CONCURRENT_SESSIONS = 50`). At cap →
+   **`failed`**.
+6. A `Session` is created **with `useMux: true`** (so it runs inside tmux),
+   registered, listeners attached, and started via `startInteractive()`
+   (`startShell()` for `shell` mode). Model/claudeMode come from global config.
+   Run status → **`session_started`**.
+7. **Readiness wait** (async, non-blocking): for non-shell agents the service
+   polls the terminal buffer up to **60 × 500ms** for a `❯` prompt or the string
+   `tokens`, then settles **2000ms** (`CRON_READY_SETTLE_MS`). Shell mode waits
+   1000ms, then sends the optional `launchCommand` as the first input line
+   (+1000ms settle).
+8. The prompt is delivered (`typed`/`paste`, trailing `\r`). Run status →
+   **`prompt_sent`**; `finishedAt` stamped. Delivery failure (e.g. the mux
+   session is gone) → **`failed`**.
+
+The created session is a **normal, persistent interactive session** — it appears
+as its own tab and keeps running after the prompt is sent. The run's
+`createdSessionUrl` is a deep link (`/?session=<id>`); the UI focuses it
+automatically after **Run Now**.
+
+> ⚠️ **Session-cap math if you disable auto-close.** With
+> `autoClosePreviousSession: false`, nothing ever closes the sessions a
+> recurring job creates — an interval job every 30 min creates 48 tabs/day and
+> hits the global 50-session cap in ~25 hours (sooner with existing tabs), after
+> which **every** fire of **every** job fails with "Maximum concurrent sessions
+> reached" until you delete tabs by hand. Leave auto-close on for unattended
+> recurring jobs, or clean up sessions yourself.
+
+### The background tick
+
+`tickDueJobs()` runs every **30s** (`CRON_TICK_INTERVAL`, registered in
+`server.ts`). For each enabled job whose `nextRunAt ≤ now`:
+
+- **Duplicate-launch guard**: `lastDueKey = jobId:fireTime`. If this due time was
+  already consumed (overlap/restart), the job is just advanced, not relaunched.
+- The schedule is **advanced _before_ launching** so a slow launch can't be
+  re-triggered by the next tick.
+- On boot, `init()` recomputes `nextRunAt` for loaded jobs (dead `once` jobs stay
+  dead).
+
+---
+
+## 9. Run history & statuses
+
+Each job keeps a history of `CronJobRun` records. Statuses (`CronJobRunStatus`):
+
+| Status            | Meaning                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `created`         | Run record created; prompt/session not yet started.           |
+| `session_started` | Session launched successfully.                                |
+| `prompt_sent`     | Prompt delivered — the happy-path terminal state.             |
+| `failed`          | Something went wrong (see `errorMessage`).                    |
+| `skipped`         | A scheduled fire was skipped by `skip_if_same_agent_running`. |
+
+Each run also records `triggerType` (`scheduled` or `manual_run_now`),
+`sessionId`/`sessionName`, timestamps, and `createdSessionUrl`.
+
+**History is capped globally** at **500 records** (`MAX_CRON_RUN_HISTORY`); the
+oldest are pruned first. Deleting a job also deletes its run records.
+
+---
+
+## 10. API reference
+
+All responses use the standard `ApiResponse<T>` envelope (`{success, data}` /
+`{success, error, errorCode}`). `/api/v1/*` is a stable alias.
+
+| Method   | Endpoint                     | Body                   | Returns                           |
+| -------- | ---------------------------- | ---------------------- | --------------------------------- |
+| `GET`    | `/api/cron/jobs`             | —                      | `CronJob[]`                       |
+| `POST`   | `/api/cron/jobs`             | `CronJobSchema`        | `{ job }`                         |
+| `GET`    | `/api/cron/jobs/:id`         | —                      | `CronJob` (404 if missing)        |
+| `PUT`    | `/api/cron/jobs/:id`         | partial `CronJob`      | `{ job }` (400 if merge invalid)  |
+| `DELETE` | `/api/cron/jobs/:id`         | —                      | `{}`                              |
+| `PUT`    | `/api/cron/jobs/:id/enabled` | `{ enabled: boolean }` | `{ job }`                         |
+| `POST`   | `/api/cron/jobs/:id/run`     | —                      | `{ run, activeAgents }`           |
+| `GET`    | `/api/cron/jobs/:id/runs`    | —                      | `CronJobRun[]` (newest first)     |
+| `GET`    | `/api/cron/runs`             | —                      | all `CronJobRun[]` (newest first) |
+
+---
+
+## 11. SSE events
+
+Emitted on `/api/events`, mirrored in `SSE_EVENTS` (`constants.js`):
+
+| Event              | Payload      | When                                                                 |
+| ------------------ | ------------ | -------------------------------------------------------------------- |
+| `cron:jobsChanged` | `{ jobs }`   | Any job created / updated / enabled / status change.                 |
+| `cron:jobDeleted`  | `{ id }`     | A job was deleted.                                                   |
+| `cron:runCreated`  | `CronJobRun` | A run (incl. skips) started.                                         |
+| `cron:runUpdated`  | `CronJobRun` | A run advanced state (`session_started` / `prompt_sent` / `failed`). |
+
+---
+
+## 12. State & persistence
+
+Persisted in `~/.codeman/state.json` via `StateStore`:
+
+- `AppState.cronJobs` — map of `id → CronJob`.
+- `AppState.cronJobRuns` — map of `id → CronJobRun`.
+
+Jobs and their schedules survive restarts; `init()` recomputes `nextRunAt` on
+boot. Sessions the jobs create persist through the normal session-recovery path.
+
+---
+
+## 13. Limits & constants
+
+| Constant                 | Value                 | Source                                           |
+| ------------------------ | --------------------- | ------------------------------------------------ |
+| Due-tick interval        | 30s                   | `CRON_TICK_INTERVAL` (`config/server-timing.ts`) |
+| Readiness poll           | 60 × 500ms            | `CRON_READY_MAX_ATTEMPTS`                        |
+| Readiness settle         | 2000ms                | `CRON_READY_SETTLE_MS`                           |
+| Run-history cap (global) | 500                   | `MAX_CRON_RUN_HISTORY` (`config/map-limits.ts`)  |
+| Saved-jobs cap           | 100                   | `MAX_CRON_JOBS` (`config/map-limits.ts`)         |
+| Concurrent-session cap   | 50                    | `MAX_CONCURRENT_SESSIONS`                        |
+| Prompt-file size cap     | 1 MiB                 | `MAX_PROMPT_FILE_BYTES` (`cron-service.ts`)      |
+| `name` length            | 1–200                 | `CronJobSchema`                                  |
+| `promptText` length      | ≤ 100000              | `CronJobSchema`                                  |
+| `intervalMinutes`        | 1–525600              | `CronJobSchema`                                  |
+| `weeklyDays`             | 1–7 entries, each 0–6 | `CronJobSchema`                                  |
+
+---
+
+## 14. Known limitations
+
+- **Server-local timezone only** — `daily`/`weekly` times are interpreted in the
+  host's local time; there is no per-job timezone.
+- **Interval drift** — `interval` re-anchors to the actual fire time; long-running
+  intervals slowly shift.
+- **Single-line prompts** — multi-line prompts are rejected (schema, form, and
+  at fire time for prompt files); tell the agent to read a file itself for
+  multi-line instructions.
+- **`runNow` / tick race** — a manual Run Now firing at the same instant as a
+  scheduled tick is theoretically possible; benign (you may get two sessions).
+- **`{enabled:true}` on a dead `once` job** — re-enabling a fired one-time job
+  without changing its schedule leaves it enabled-but-dead (won't fire); change
+  the schedule to re-arm.
+
+---
+
+## 15. Troubleshooting
+
+| Symptom                        | Likely cause                                                                                                      | Fix                                                                                                  |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Job never fires                | Disabled, or `nextRunAt: null`                                                                                    | Check **Enabled**; verify the schedule fields are complete.                                          |
+| Run shows `failed` immediately | Bad `workingDir`, prompt-file rejected, or session cap hit                                                        | Read `errorMessage` on the run; confirm the dir exists and the prompt file is inside it and < 1 MiB. |
+| Run shows `skipped`            | `skip_if_same_agent_running` + another live same-type session (this job's own sessions and dead tabs don't count) | Switch to `warn_only`, or wait for the other session to end.                                         |
+| Run fails with "single line"   | Multi-line prompt text / prompt file                                                                              | Keep the prompt to one line; point the agent at a file to read for long instructions.                |
+| Sessions pile up between runs  | `autoClosePreviousSession: false`                                                                                 | Re-enable auto-close, or delete old tabs before the 50-session cap bites (see §8).                   |
+| Wrong fire time                | Timezone assumption                                                                                               | Times are **server-local** — check the host clock/TZ.                                                |
+| One-time job won't re-fire     | `completedOnce` set                                                                                               | Edit the schedule (any real schedule change re-arms it).                                             |
+
+---
+
+## 16. Related docs
+
+- `docs/cron-discovery.md` — architecture / integration-point analysis (why the
+  feature reuses the session layer and stays distinct from `ScheduledRun`).
+- `docs/cron-build-brief.md` — the original build brief / requirements.
+- `CLAUDE.md` → **Key Patterns → Cron** — the one-paragraph engineering summary.
+- Tests: `test/cron-time.test.ts` (schedule math), `test/cron-service.test.ts`
+  (CRUD, tick, concurrency, security).

docs/docker-cases-plan.md

@@ -0,0 +1,433 @@
+<!-- Design doc generated via ultracode multi-agent workflow (wf_e3a7498b-26f): 3 architecture proposals -> judge panel -> synthesis -> completeness critic. -->
+
+# Docker Session Mode, Implementation Plan
+
+## Decisions (locked 2026-07-19, by repo owner)
+
+1. **Isolation posture**: CONVENIENT default (bind-mount host `~/.claude` etc. read-write so the existing login just works; network on; still hardened non-root + cap-drop + resource caps). SEALED profile (`mountCredentials:false` + `network:none`) is a per-case opt-in.
+2. **Export**: offer BOTH full-image (`commit`+`save`+workspace tar) AND workspace-only, side by side, no default (ask each time).
+3. **Base image**: BUILD LOCALLY on first use via `scripts/build-agent-image.mjs` from a repo `docker/agent.Dockerfile`. No registry required. (GHCR pull can be added later.)
+4. **Hooks**: WIRE HOOKS NOW. Codeman scaffolds `.claude/settings.local.json` + CLAUDE.md into the linked host workspace dir (same as local cases), enabling in-container permission prompts, hook-idle detection, and the Claude Model picker.
+
+Adopted defaults for the remaining open items (Section 10): resume-on-restart ON; container is per-CASE and shared by multiple sessions (killing one session only kills its in-container tmux session, never `docker stop` while siblings remain; stop/remove only on explicit teardown or case-delete); rootless caps = ship-with-warning (`capsEnforced` surfaced); remote docker daemon = local-first; podman = docker-first best-effort.
+
+## Implementation status (branch `feat/docker-session-mode`)
+
+DONE and END-TO-END VERIFIED against a real docker daemon (create host, link case, quick-start shell in a real container, workspace bind-mount round-trip, hook scaffolding, session-delete keeps the shared container up, case-delete `docker rm`s it):
+
+- Phase 0-1: types (`DockerHost`/`DockerCase`/`SessionDocker`), `src/docker-hosts.ts` (storage, pure `buildDockerBaseArgs`/`buildDockerCreateArgs`, `containerApiUrl`, `hostGatewayAlias`, config-hash, credential-mount resolution, daemon probes), `DockerHostSchema`/`DockerCaseLinkSchema`. 26 unit tests.
+- Phase 2: `tmux-manager` `buildDockerLaunchCommand` (image-check -> ensure -> start -> exec, resume-aware), `buildDockerKillCommand` (in-container tmux only, multi-session safe), stop/remove; wired into `createSession`/`respawnPane`/`killSession`. 14 unit tests.
+- Phase 3: `Session` threading (`_docker`, toState, option builders, in-container cliVersion probe, `resolveMuxAttachCwd`), `server.ts` recovery round-trip.
+- Phase 4: `case-routes` `/api/docker-hosts` CRUD + `/api/cases/docker-link` + listing + docker-unlink; `session-routes` `/api/quick-start` docker branch (rejects per-session config, probes availability + tmux, scaffolds hooks, seeds resume id).
+- Phase 5 (partial): `docker/agent.Dockerfile` + `scripts/build-agent-image.mjs` (built + verified: node 22, tmux, claude/codex/gemini/opencode, arbitrary-uid HOME). Host-guard allowlists `host.docker.internal`/`host.containers.internal` for in-container hooks.
+- Full CI green (3445 tests).
+
+REMAINING:
+
+- Phase 6: export / import (`docker commit` + `save | gzip` + workspace tar + manifest; `load` + quarantined re-tag), GC / boot reaper, disk-safety prechecks, drift-recreate route, SSE `docker:*` events. THE "move to a new machine" feature.
+- Phase 7: frontend Create Case "Docker" tab + `linkDockerCase` + run wiring + case-picker labels + export/import UI.
+- Phase 8: CLAUDE.md "Docker cases" Key Pattern + `docs/docker-cases.md` + COM.
+- Deferred refinements: in-container model-picker via `settings.local.json`; live mid-run resume-id capture into `DockerCase.lastClaudeSessionId`; rootless/Desktop uid probe (currently a platform heuristic).
+
+## 1. Goal & user stories
+
+Add "Docker cases" to Codeman: a case can point at a container instead of a local or remote-SSH path, and any of the five CLI backends (`claude` / `shell` / `opencode` / `codex` / `gemini`) runs inside that container. It is modeled as a LOCATION OVERLAY on cases, exactly like the remote-SSH feature (COD-94/#145), never as a sixth `SessionMode`.
+
+User stories:
+
+- As the repo owner, I link a case to a per-project container so an autonomous Claude/Ralph run executes in a hardened sandbox (cap-drop, non-root, resource caps) instead of directly on my host, while keeping my existing OAuth login and transcript history working with zero extra setup.
+- I set default, per-case-changeable container settings (image, network mode, memory/cpu/pids caps) at link time and edit them later, and edits actually take effect through a recreate-on-drift path (see Section 4).
+- I reconnect after a Codeman restart and land back in the SAME running agent with the conversation intact. When the CONTAINER itself was stopped/rebooted/OOM-killed (which destroys the in-container tmux), the next launch RESUMES the last conversation from the bind-mounted transcript rather than starting fresh (durability model in Section 2, Key decision 1).
+- I export a finished run's whole environment (toolchain plus workspace) to a portable, secret-free `.tar.gz`, move it to another machine, and import it back into a fresh case in one click.
+- The container never accumulates: killing the session stops it, deleting the case removes it, and an instance-scoped boot reaper reaps containers whose case is gone.
+
+Non-goals for the MVP: multi-tenant untrusted-code isolation guarantees (Codeman is loopback-default and single-operator, and the agent already runs `--dangerously-skip-permissions` on the host today), Kubernetes/compose orchestration, and per-command ephemeral containers.
+
+## 2. Chosen architecture and why
+
+The design grafts the strongest idea from each of the three proposals:
+
+- Overlay-not-a-mode + faithful remote-SSH mirror (from "Docker Cases as a Location Overlay"): lowest churn, rides the existing quick-start / mux-sessions / state / recovery plumbing.
+- Convenient-but-hardened default with an opt-in sealed profile, plus exec-time name-only secret env (from "Sealed Sandbox"): a strict security improvement over today's on-host execution without the UX tax of forcing an in-container re-login.
+- One-artifact export + in-app import route (from "Container-as-Cargo"): the genuinely new, high-value capability Codeman lacks.
+
+### Key decision 1: persistent per-CASE container, durable in-container tmux, AND resume-on-restart (the two-layer durability model)
+
+Exactly one long-lived container per Docker case, named as a pure slug function `codeman-case-<slug>` (Docker charset `^[a-zA-Z0-9][a-zA-Z0-9_.-]+$`; Codeman already slugs case names for tmux), so create-if-missing and boot recovery are idempotent. PID1 is `sleep infinity` under `--init` (tini reaps zombies and forwards `docker stop`'s SIGTERM); the CLI is NOT the container command. The CLI runs inside a DURABLE in-container tmux on a dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>`, the direct analog of remote's `-L codeman-remote` / `codeman-ssh-<id8>`.
+
+Two DIFFERENT failure surfaces need two DIFFERENT recovery layers, and conflating them is the central flaw the critic caught:
+
+1. Codeman-PROCESS restart while the container stays up: the in-container tmux is still alive, so `tmux new-session -A` (attach-or-create) reattaches the SAME live agent and the paneCommand is ignored. This is the remote-SSH durability idiom and it works unchanged.
+2. CONTAINER stop / daemon restart / host reboot / OOM-kill: the in-container tmux is GONE (fresh PID1). `new-session -A` will now CREATE a fresh session and run the paneCommand, which would start a brand-new conversation. This is the case the raw plan silently lost. Because the transcript directory is bind-mounted from the host (Key decision 3), the fix is to launch with RESUME: the paneCommand becomes `exec claude --dangerously-skip-permissions --resume <claudeSessionId>` (codex uses `resume <id>`, gemini `--resume <id>`) whenever a captured `claudeSessionId` exists. The `-A` semantics make this self-selecting: the resume flag only ever executes when tmux is actually re-created, which is exactly when the live session was lost. When tmux is still alive (case 1), attach wins and the flag is inert.
+
+Capturing / persisting / reusing the resume id (the missing mechanism the critic flagged): Codeman already learns `Session.claudeSessionId` from transcript correlation (which works here because projHash matches, Key decision 3) and persists it in `SessionState`. We thread that value into `createSessionOptions` / `respawnPaneOptions` for docker so `buildDockerLaunchCommand` can inject the resume flag on any relaunch. To make a NEW Codeman session (new `id8`) re-launched against the same case resume its predecessor's conversation, we ALSO persist `lastClaudeSessionId` on the `DockerCase` record; the quick-start docker branch seeds the new `Session` with it when the `dockerResumeOnStart` setting is on. First-ever launch has no id, so it starts fresh. This is user-decision 7 (default resume behavior).
+
+Reconciling with stop-on-kill and with the `--restart` policy (the internal inconsistency the critic found): the container is created with `--restart no` uniformly (Codeman's idempotent create-if-missing plus boot recovery is the single recovery mechanism; a restart policy would not preserve the conversation anyway because a restarted container gets a fresh PID1/tmux). Boot recovery re-runs `buildDockerLaunchCommand` from the restored `MuxSession.docker` (`docker inspect || docker create; docker start`, then exec with resume), so a host reboot or daemon restart recreates+starts the container and resumes the conversation instead of the session vanishing. `reconcileSessions` (tmux-manager.ts ~1800-1815) must NOT hard-delete a docker session merely because no LOCAL pane exists after the local `-L codeman` server died; docker (like remote) sessions are restored from `mux-sessions.json` and relaunched. This relaunch path is explicitly part of Phase 4/Phase 3 recovery work, not assumed.
+
+Why this over the alternatives: `docker exec` gets SIGHUP and dies when its client TTY closes, so a bare `docker exec claude` restarts the CLI on every reconnect/respawn. The inner tmux plus resume is what makes reconnect idempotent across BOTH failure surfaces. Because this durability is the single most important design point, tmux-in-image is a HARD gated prerequisite (`checkDockerTmuxAvailable`), never a silent fallback to bare exec. Rejected alternatives: ephemeral-per-run or bare-exec containers (no reattach durability); a literal `'docker'` `SessionMode` (touches dozens of switch/enum sites and diverges from the remote overlay precedent, since Docker is a LOCATION orthogonal to the 5 CLI backends).
+
+### Key decision 2: CLI + auth delivery
+
+One prebuilt base image (built once, contains NO secrets): `node:22-bookworm-slim` + `git tmux ripgrep ca-certificates`, `npm i -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai`, an `agent` user, HOME dirs made writable by an arbitrary host uid via the OpenShift "gid 0, group-writable" convention (Key decision 6). Because the toolchain is baked, export is reproducible and needs no network at import time. The image name/namespace/registry and its refresh cadence are user-decision 2 (the `codeman/agent:base` placeholder implies a Docker Hub org the project may not own).
+
+Credentials are delivered ONLY at runtime, two commit-safe channels, default convenient:
+
+- OAuth/config-file CLIs (Claude Max/Pro, gcloud, opencode): bind-mount the host credential dirs read-write (`~/.claude`, `~/.codex`, `~/.gemini` + `~/.config/gcloud`, `~/.config/opencode`) so the common user "just works" with no in-container login. Because these are bind mounts, `docker commit` (which captures only the container's own writable layer, never bind mounts) physically cannot capture them, so exports stay secret-free.
+- API-key CLIs (codex/gemini): exec-time NAME-ONLY `docker exec --env OPENAI_API_KEY --env GEMINI_API_KEY ...` (no `=value`), sourced from Codeman's own process env. Only the key NAME appears in argv (no `ps` leak), and per-exec env is never captured by `docker commit`. This is the technique Codeman already uses via `tmux setenv` for the local Codex/Gemini panes, so it composes with existing machinery.
+
+Per-host `DockerHost.mountCredentials` defaults `true` (convenient); setting it `false` yields a SEALED profile (no host cred mounts, in-container login only) for genuinely untrusted work. CRITICAL sealed-mode export rule (the leak the critic caught): in sealed mode the in-container login writes tokens into the container's OWN writable layer, which `docker commit` DOES capture, so a full-image export of a sealed container would ship credentials. Therefore full-image export is REFUSED for `mountCredentials:false` containers by default; the user may either take a workspace-only export (always safe) or opt into a pre-commit scrub that `docker exec`s `rm -rf ~/.claude ~/.codex ~/.gemini ~/.config/gcloud ~/.config/opencode` inside the container before commit (destructive to the in-container login, which is the point). This is enforced in the export route, not left to a manifest assertion.
+
+Per-session `envOverrides` / `effort` / `codexConfig` / `geminiConfig` / `openCodeConfig` are REJECTED at quick-start exactly like the remote branch (session-routes.ts ~1698-1710). `modelOverride` is the one deliberate difference from remote: because the docker workspace is a REAL bind-mounted host dir that Codeman scaffolds (Key decision 5 and Section 6), `updateCaseModel()` can write the `model` key into `<workspace>/.claude/settings.local.json` and the in-container `claude` reads it, so the App Settings Claude Model picker works for docker cases. `effort` is a `--effort` CLI arg applied only by the local-spawn path we bypass, so it stays rejected (surfaced honestly in the UI, not silently inert). Per-mode command customization goes through `DockerHost.commands.<mode>` (`defaultDockerCommandForMode`, mirror of `defaultRemoteCommandForMode` at remote-hosts.ts:60). NEVER bake secrets into an image layer and NEVER pass a secret via create-time `-e` (both are committed).
+
+Rejected alternative: sealed-by-default. For a single-operator loopback tool where the agent already runs skip-permissions on the host, forcing an in-container OAuth re-login is a UX regression with little real gain. We keep sealed as an opt-in. Rejected alternative: baking a login into the image, which leaks the instant you `docker save`.
+
+### Key decision 3: workspace mount, container CWD, and transcript correlation
+
+Bind-mount the host workspace dir into the container at the SAME absolute path (`dst == src`, mirror the host path), and set both `Session.workingDir` and the container workdir to that host path.
+
+Two problems this solves that the raw proposals got wrong:
+
+- File features: `DockerCase.hostWorkspacePath` is a REAL host directory, so `Session.workingDir = hostWorkspacePath` keeps file-routes, attachments, image-watcher, and previews working on real host bytes (unlike remote, where the path is remote-only and those features no-op). All three proposals wired `casePath = <container path>`; we deliberately diverge and use the host path.
+- Transcript correlation: Claude writes transcripts under `~/.claude/projects/<hash-of-CWD>/`. By mirroring the host path as the container CWD, the projHash computed inside the container equals the host-side hash Codeman's transcript/subagent/workflow watchers expect, so correlation keeps working (and, in turn, feeds the resume-id capture in Key decision 1). A `/workspace`-style fixed dst would break it. Mirror-vs-fixed is user-decision 3.
+
+`resolveMuxAttachCwd` still returns `/tmp` for docker sessions (the LOCAL bash pane only runs `docker exec`; it never needs the workspace as its cwd), mirroring remote.
+
+### Key decision 4: network default and the engine-specific host gateway
+
+Default `bridge` (own netns, NAT egress, no inbound), per-case changeable to `none` (offline shell sandbox; warned because it breaks the API CLIs) or `custom` (a user-defined bridge `codeman-net-<slug>`, the chokepoint for a future egress allowlist). `host` networking and any `-p` inbound publish are structurally unrepresentable in the flag builder and schema. Rationale: every API-backed CLI (Claude, Codex, Gemini) plus npm/git needs egress, so `bridge` is the only sane functional default; `none` is reserved for `shell`.
+
+The host-callback gateway alias is ENGINE-SPECIFIC (the critic's podman finding): Docker uses `host.docker.internal`, Podman uses `host.containers.internal` (Docker's alias only exists on recent podman). A helper `hostGatewayAlias(engine)` returns the right name; Section 2.5, the create args, the `CODEMAN_API_URL` rewrite, and the host-guard allowlist all consume it, and BOTH aliases are added to the allowlist so a mixed fleet keeps working.
+
+### Key decision 5: hooks actually reach the host AND are actually installed
+
+Two independent things must both be true for a hook to fire, and the raw plan wired only the first:
+
+1. Network reachability. Claude Code hooks POST to `$CODEMAN_API_URL` (`curl -sk`). Inside a bridge container `localhost` is the container and prod binds `127.0.0.1`, so we set `--add-host <gatewayAlias>:host-gateway` on create (skipped on Docker Desktop, where the alias is native), add the gateway alias to the host guard, and provide `CODEMAN_API_URL` and the hook secret (below).
+2. Hook INSTALLATION. Hooks live in `<workspace>/.claude/settings.local.json`, written by the quick-start scaffolding block (around session-routes.ts ~1776) that calls `writeHooksConfig()` / `updateCaseModel()`. The raw plan extended the `!remote` guard to `!remote && !docker`, which would SKIP that block and silently disable ALL hooks regardless of networking. For docker the workspace is a REAL bind-mounted host dir, so the scaffolding block MUST run. Precise fix: extend to `!remote && !docker` ONLY the LOCAL-CLI-availability and local-spawn guards (the ones that stat the local binary or build the local spawn command); leave the workspace-scaffolding guard at `!remote` so it runs for docker. This same decision is what makes `modelOverride` work (Key decision 2). Consequence, surfaced as user-decision 4: linking a docker case now WRITES `.claude/settings.local.json` (and the CLAUDE.md scaffold, matching local-case behavior) into the user's real host directory, a behavioral shift from "link a dir" to "link and scaffold a dir."
+
+`CODEMAN_API_URL` derivation (the wrong-scheme bug the critic caught): prod is HTTPS-only on 3000, and `server.ts` (~2000) auto-sets `process.env.CODEMAN_API_URL = ${protocol}://${apiHost}:${port}`. Hardcoding `http://host.docker.internal:3000` fails every hook. Instead a pure helper `containerApiUrl(process.env.CODEMAN_API_URL, engine)` parses the running URL and substitutes ONLY the hostname with `hostGatewayAlias(engine)`, preserving scheme and port (`https://host.docker.internal:3000`). Unit-tested against http, https, non-default ports, and both engines. Passed as create-time `--env CODEMAN_API_URL=<derived>` (case-stable, non-secret).
+
+Hook secret and session attribution:
+- `~/.codeman/hook-secret` is bind-mounted read-only to a container path; `--env CODEMAN_HOOK_SECRET_FILE=<that path>` is create-time (a path is non-secret; the bytes ride the bind mount and are never committed).
+- `CODEMAN_SESSION_ID` (which the generated hooks reference at hooks-config.ts:78-80 to attribute events) plus `CODEMAN_MUX=1` are SESSION-scoped, so they are passed at EXEC time via `docker exec --env CODEMAN_SESSION_ID=<id> --env CODEMAN_MUX=1` (non-secret, value inline is fine, and exec env is not committed). Because a `tmux` session started fresh only inherits the invoking env when it starts the SERVER, the launch chain ALSO runs `tmux -L codeman-docker setenv -g CODEMAN_SESSION_ID <id>` (and `CODEMAN_MUX`) so reattaches and newly created panes see the same values. This mirrors how Codeman already injects per-session env into tmux for the external CLIs.
+
+Hooks-in-MVP-vs-deferred stays user-decision 4; if deferred, docker ships as explicitly hook-degraded and we lean on output-based idle detection through the docker-exec PTY.
+
+### Key decision 6: uid / HOME / rootless enforcement / macOS Docker Desktop
+
+The raw plan showed `--user 1000:1000` in one place and `--user "$(id -u):$(id -g)"` in another and never resolved HOME writability; this section fixes all of it.
+
+- Linux native (docker rootful or rootless): run `--user <hostUid>:0` (host uid, GID 0). The image follows the OpenShift arbitrary-uid convention: `HOME=/home/agent`, and `/home/agent` plus the tool cache dirs (`~/.npm`, `~/.cache`, `~/.config`) are owned `root:0` and group-writable (`chmod -R g+w`, `g+s` on dirs) so a process with GID 0 can write HOME even though its UID is not 1000. This keeps workspace files host-owned (the agent's UID is the host UID) AND keeps HOME writable, so the CLIs actually start.
+- Podman rootless: use `--userns=keep-id` (maps the host uid to the image's `agent` uid inside the container) instead of `--user`, so `/home/agent` is owned by the running user and workspace files are host-owned. This is a real per-engine branch in `buildDockerCreateArgs`.
+- macOS Docker Desktop: `--user <macUid>` (e.g. 501) does not own the image's `/home/agent`, so non-bind HOME writes fail EACCES and the CLIs may not start; Desktop also does its own bind-mount uid translation, provides `host.docker.internal` natively (no `--add-host`), and its VM memory ceiling can cap `--memory`. Detect Desktop via `docker info` (Server OS `linuxkit` / `OperatingString` contains "Docker Desktop") and take a dedicated path: do NOT pass `--user` (run as the image's baked `agent` uid and rely on Desktop's translation for workspace access), skip `--add-host`, and note in the UI that memory caps are subject to the VM ceiling.
+
+Rootless resource-cap enforcement (the silently-inert risk): rootless Docker without cgroup-v2 systemd delegation (`Delegate=yes`) silently IGNORES `--memory`/`--cpus`/`--pids-limit`. The probe checks `docker info` for `CgroupVersion=2` plus rootless plus delegation; if caps cannot be enforced, `checkDockerAvailable` returns `capsEnforced:false` and the link/probe surfaces "resource caps are advisory on this engine." Whether to REQUIRE delegation or ship-with-warning is user-decision 6.
+
+## 3. Data model
+
+New TypeScript types in `src/types/session.ts`, added right after the remote types (lines 46-99). SessionMode (line 44) is UNCHANGED.
+
+```ts
+export type DockerCommandMode = Extract<SessionMode, 'shell' | 'claude' | 'opencode' | 'codex' | 'gemini'>;
+export type DockerEngine = 'docker' | 'podman';
+export type DockerNetworkMode = 'bridge' | 'none' | 'custom'; // never 'host'
+
+export interface DockerResourceLimits {
+  memory?: string;    // '4g'  -> --memory 4g --memory-swap 4g (swap==memory: real OOM cap)
+  cpus?: string;      // '2'
+  pidsLimit?: number; // 512   (fork-bomb guard)
+  nofile?: string;    // '4096:8192'
+  shmSize?: string;   // optional; only when a tool needs /dev/shm
+}
+
+export interface DockerHost {
+  id: string;
+  label: string;
+  engine?: DockerEngine;             // default resolved by probe (docker, else podman)
+  image: string;                     // default resolved image ref (see user-decision 2)
+  daemonHost?: string;               // advanced: -H ssh://user@host / DOCKER_HOST
+  context?: string;                  // advanced: --context <ctx>
+  network?: DockerNetworkMode;       // default 'bridge'
+  networkName?: string;              // when network === 'custom'
+  resources?: DockerResourceLimits;
+  mountCredentials?: boolean;        // default true (false = sealed; blocks full-image export)
+  hooksEnabled?: boolean;            // default true (host-gateway callback wiring)
+  resumeOnStart?: boolean;           // default true (see Key decision 1 / user-decision 7)
+  commands?: Partial<Record<DockerCommandMode, string>>;
+  extraCreateArgs?: string[];        // validated like extraSshOptions
+  extraExecArgs?: string[];
+}
+
+export interface DockerCase {
+  name: string;
+  type: 'docker';
+  hostId: string;
+  hostWorkspacePath: string;         // absolute HOST dir: bind src + Session.workingDir
+  containerWorkdir?: string;         // container path; default = hostWorkspacePath (mirror -> projHash match)
+  container?: string;                // default codeman-case-<slug>
+  lastClaudeSessionId?: string;      // captured resume id (Key decision 1)
+}
+
+export interface SessionDocker {     // flattened, round-trips through mux/state (mirror SessionRemote at 91)
+  hostId: string;
+  label: string;
+  engine: DockerEngine;
+  image: string;
+  containerName: string;
+  hostWorkspacePath: string;
+  containerWorkdir: string;
+  network: DockerNetworkMode;
+  networkName?: string;
+  resources?: DockerResourceLimits;
+  mountCredentials: boolean;
+  hooksEnabled: boolean;
+  resumeOnStart: boolean;
+  daemonHost?: string;
+  context?: string;
+  commands?: Partial<Record<DockerCommandMode, string>>;
+  extraCreateArgs?: string[];
+  extraExecArgs?: string[];
+  configHash?: string;               // drift detection (Key decision, Section 4)
+}
+```
+
+- `SessionState` gains `docker?: SessionDocker` immediately after `remote?` (line 219). It persists automatically because `SessionState` is structural and `state-store.ts` stores `toState()` verbatim.
+- `src/mux-interface.ts`: add `docker?: SessionDocker` to `MuxSession` (after line 38), `CreateSessionOptions` (after 81), `RespawnPaneOptions` (after 105). `MuxSession.docker` round-trips through `mux-sessions.json` automatically.
+- `src/types/api.ts` `CaseInfo`: add `'docker'` to the `location` union and a `docker?: { hostId; container; image?; path; network }` display block.
+- `src/services/unified-session-service.ts`: add a boolean `docker?` flag on `UnifiedSessionItem` and source rows, set from `MuxSession.docker` presence (mirror the `remote` flag at ~line 200 and the harvest at session-routes.ts:2313).
+
+New state files (all via `dataPath()`, mirroring `remote-hosts.json` / `remote-cases.json`):
+
+- `~/.codeman/docker-hosts.json` (reusable engine/image/network/resource profiles).
+- `~/.codeman/docker-cases.json` (`name -> DockerCase`, including `lastClaudeSessionId`).
+- `~/.codeman/docker-exports/` (dedicated dir for `.image.tar.gz` + `.workspace.tar.gz` + `manifest.json`; never inline in state.json; retention/pruning per Section 5).
+
+No new `state.json` / `mux-sessions.json` files: `SessionState.docker` and `MuxSession.docker` ride the existing serialization.
+
+## 4. Container lifecycle (exact command shapes)
+
+All builders are PURE string functions (directly unit-testable). Host values interpolated into the outer `bash -c "..."` layer (container name, image, workdir, host paths) are `shellescape()`'d and, for user-supplied fields, schema-rejected for `$`/backtick via `NO_SHELL_META`. The escaping chain here is DEEPER than remote's single `ssh '<tmux ...>'`: the whole `docker inspect || docker create <dozens of --mount/--env/shellescaped host paths>` is interpolated into `bash -c "..."` then `JSON.stringify`'d into respawn-pane. This is a known place to get stuck, so it is covered by concrete escaping tests (Section 9), including host workspace paths containing spaces, not just a "we call shellescape" claim.
+
+New in `src/tmux-manager.ts`:
+
+```ts
+const DOCKER_TMUX_SOCKET = 'codeman-docker';
+// 'dkr' letters deliberately FAIL SAFE_MUX_NAME_PATTERN (^codeman-[a-f0-9-]+$),
+// so a Codeman running INSIDE the container never adopts/resizes/respawns our session.
+export function dockerTmuxSessionName(id: string): string { return `codeman-dkr-${id.slice(0, 8)}`; }
+```
+
+`buildDockerBaseArgs(docker)` (pure, in `docker-hosts.ts`, mirror of `buildSshConnectionArgs`) emits the engine prefix tokens: `docker` (or `podman`) + optional `--context <ctx>` or `-H <daemonHost>`. `buildDockerCreateArgs(docker, sessionId)` emits the `docker create` flag array (with the per-engine uid/userns branch from Key decision 6).
+
+IMAGE PRESENCE (before any create, the auto-pull footgun the critic caught): the launch chain runs `docker image inspect <image> >/dev/null 2>&1` first; on miss it exits with a distinct message ("base image <ref> not present: build with scripts/build-agent-image.mjs or pull it") rather than triggering a blocking multi-GB auto-pull inside the tmux pane. `docker create` carries `--pull=never`. The tmux-availability probe likewise uses `docker run --rm --pull=never <image> sh -lc 'command -v tmux'` and reports the same build/pull hint if the image is absent, so the 15s-bounded probe never hangs on a pull.
+
+CREATE (the ensure step, embedded in the launch string):
+
+```
+docker create \
+  --name codeman-case-myproj --hostname myproj \
+  --label codeman.managed=1 --label codeman.instance=<CODEMAN_INSTANCE> \
+  --label codeman.case=myproj --label codeman.session=<id8> \
+  --label codeman.confighash=<hash> \
+  --pull=never --init --restart no \
+  --user 1000:0 \
+  --workdir '/home/arkon/cases/myproj' \
+  --mount type=bind,src='/home/arkon/cases/myproj',dst='/home/arkon/cases/myproj' \
+  --mount type=bind,src='/home/arkon/.claude',dst='/home/agent/.claude' \
+  --mount type=bind,src='/home/arkon/.codeman/hook-secret',dst='/home/agent/.codeman/hook-secret',readonly \
+  --add-host host.docker.internal:host-gateway \
+  --memory 4g --memory-swap 4g --cpus 2 --pids-limit 512 --ulimit nofile=4096:8192 \
+  --cap-drop ALL --security-opt no-new-privileges \
+  --network bridge \
+  --env HOME=/home/agent --env TERM=xterm-256color --env COLORTERM=truecolor \
+  --env CODEMAN_API_URL=https://host.docker.internal:3000 \
+  --env CODEMAN_HOOK_SECRET_FILE=/home/agent/.codeman/hook-secret \
+  codeman/agent:base \
+  sleep infinity
+```
+
+- `--user 1000:0` shown is the Linux-native form with GID 0 (Key decision 6); it is actually `--user <hostUid>:0`, or `--userns=keep-id` for podman rootless, or omitted on Docker Desktop. The literal is illustrative only.
+- Create-time `--env` carries only NON-SESSION, non-secret, case-stable values (safe to be committed): the DERIVED `CODEMAN_API_URL` (https-preserving, Key decision 5) and the hook-secret FILE PATH. `CODEMAN_SESSION_ID`/`CODEMAN_MUX` and the codex/gemini key NAMES are exec-time only.
+- `codeman.instance=<CODEMAN_INSTANCE>` is REQUIRED on the label set so the boot reaper is instance-scoped (a beta/second instance must never reap prod's containers).
+- `codeman.confighash` is a stable hash of the drift-relevant create args (image, resources, network, mounts, non-session env). Drift detection (user story 2, the config-never-takes-effect gap): on launch the ensure block compares the desired hash to the existing container's label; on mismatch the launch does NOT silently reuse the stale container. Instead the docker route returns a "container config changed, recreate?" action (SSE + UI confirm), and on confirm Codeman `docker rm`'s and recreates. rm destroys in-image (non-bind) state, but the workspace and transcripts survive on their bind mounts and the conversation is restored via `--resume`, so the recreate is safe. Auto-recreate-vs-prompt is a UI choice; the MVP prompts.
+- `--restart no` (resolved consistently with Key decision 1; recovery is Codeman's idempotent create-if-missing, not an engine restart policy, which also matters for Podman which has no daemon).
+
+EXEC (`buildDockerLaunchCommand`, the docker analog of `buildRemoteLaunchCommand`, TTY-correct, resume-aware). The whole thing is ONE `bash -c` string that image-checks, ensures, starts, primes tmux env, then execs:
+
+```
+docker image inspect codeman/agent:base >/dev/null 2>&1 || { echo 'Codeman: base image codeman/agent:base not present (build or pull it)'; exit 1; } ; \
+docker inspect codeman-case-myproj >/dev/null 2>&1 || docker create <all create args above> ; \
+docker start codeman-case-myproj >/dev/null 2>&1 || { echo 'Codeman: container codeman-case-myproj failed to start (daemon down?)'; exit 1; } ; \
+exec docker exec -it \
+  --workdir '/home/arkon/cases/myproj' \
+  --env TERM=xterm-256color --env COLORTERM=truecolor \
+  --env CODEMAN_SESSION_ID=1a2b3c4d --env CODEMAN_MUX=1 \
+  --env OPENAI_API_KEY --env GEMINI_API_KEY \
+  codeman-case-myproj \
+  sh -lc 'tmux -L codeman-docker setenv -g CODEMAN_SESSION_ID 1a2b3c4d \; setenv -g CODEMAN_MUX 1 \; new-session -A -s codeman-dkr-1a2b3c4d -c '\''/home/arkon/cases/myproj'\'' '\''cd /home/arkon/cases/myproj && exec claude --dangerously-skip-permissions --resume <claudeSessionId>'\'' \; set -t codeman-dkr-1a2b3c4d status off \; set -t codeman-dkr-1a2b3c4d mouse off \; set -t codeman-dkr-1a2b3c4d prefix C-q \; set -s escape-time 0'
+```
+
+- `docker exec -it`: `-t` allocates a PTY and forwards SIGWINCH into the container so the Ink TUI re-lays-out on pane resize; `TERM`/`COLORTERM` prevent degraded rendering. `--env OPENAI_API_KEY` (name only) is present only for codex/gemini and is exec-time (never committed). `CODEMAN_SESSION_ID`/`CODEMAN_MUX` are exec-time values plus a `tmux setenv -g` prime so reattaches and new panes inherit them (Key decision 5).
+- `--resume <claudeSessionId>` (codex `resume <id>`, gemini `--resume <id>`) is appended to `modeCommand` ONLY when a captured id exists; on first launch it is omitted. `new-session -A` makes the flag inert on a live-tmux reattach and effective only when tmux is re-created (Key decision 1).
+- `modeCommand = docker.commands?.[mode] || defaultDockerCommandForMode(mode)` (`exec claude --dangerously-skip-permissions`, `exec bash -l`, etc.), with the resume suffix injected by the builder.
+- Escaping survives every layer identically to remote in shape but deeper in nesting: `paneCommand` (`cd ... && exec ...`) is one shellescaped tmux arg, the whole `tmuxInvocation` is one shellescaped `sh -lc` arg, and the outer string is `JSON.stringify()`'d into `bash -c` by respawn-pane (tmux-manager.ts:1329).
+
+Wire-up (extend the two existing seams to 3-way):
+
+- createSession (tmux-manager.ts:1276): `const fullCmd = docker ? buildDockerLaunchCommand({ mode, docker, sessionId, resumeSessionId }) : remote ? buildRemoteLaunchCommand({ mode, remote, sessionId }) : localFullCmd;`
+- launchCmd cd-skip (tmux-manager.ts:1327): `const launchCmd = (remote || docker) ? fullCmd : \`cd ${JSON.stringify(workingDir)} && ${fullCmd}\`;`
+- respawnPane: same two edits at lines 1524 and 1542.
+
+START / reattach-after-reboot: the ensure block (image-check, `docker inspect || docker create`, `docker start`) is fully idempotent, so boot recovery just re-runs `buildDockerLaunchCommand` from the restored `MuxSession.docker` with the persisted resume id. A rebooted host recreates the container and resumes the conversation.
+
+DOCKER-DOWN surfacing (the PTY-exit-breaker false-trip risk): if `docker start` or `docker exec` cannot attach (daemon down, container missing), the launch prints a docker-specific message and exits, which alone would still count toward `session-pty-exit-breaker` and show a generic "respawn breaker tripped" push. To avoid masking the cause, the docker reattach path runs a fast `checkDockerAvailable` pre-flight: if the daemon/container is unreachable, Codeman broadcasts a docker-specific error (SSE + push, "container <name> is not running / daemon down") and SKIPS the auto-reattach that would trip the breaker, rather than fast-looping `docker exec`.
+
+STOP / KILL (`killSession` Strategy 3c, right after remote's Strategy 3b at tmux-manager.ts:1719, guarded by `IS_TEST_MODE`):
+
+```ts
+if (session.docker) {
+  // best-effort, fire-and-forget, timeout-bounded so it never blocks the local kill
+  execAsync(buildDockerKillCommand({ docker: session.docker, sessionId }), { timeout: EXEC_TIMEOUT_MS }).catch(() => {});
+}
+```
+
+`buildDockerKillCommand` emits: `docker exec codeman-case-<slug> tmux -L codeman-docker kill-session -t codeman-dkr-<id8> ; docker stop -t 10 codeman-case-<slug>`. Stopping frees CPU/RAM and, per Key decision 1, is safe for conversation continuity because the NEXT launch resumes from the bind-mounted transcript via `--resume`. Whether to stop at all (RAM vs instant live-agent reattach) is user-decision 6/1 (reframed honestly). The bind-mounted workspace and transcripts always survive on the host.
+
+REMOVE: only on explicit case delete (`docker rm -f codeman-case-<slug>`), gated behind an "export first?" UI prompt because rm destroys any in-image (non-bind) state. Instance-scoped boot reaper (fixing the racy/cross-instance reaper): after `docker-cases.json` is loaded AND after `restoreMuxSessions` has run, enumerate `docker ps -a --filter label=codeman.managed=1 --filter label=codeman.instance=<CODEMAN_INSTANCE> --format '{{.Names}}\t{{index .Labels "codeman.case"}}'` and `docker rm -f` only containers whose case is gone from THIS instance's `docker-cases.json`. The instance filter is what stops a beta reaping prod's containers (the exact cross-instance hazard the project memory warns about).
+
+AVAILABILITY PROBE (`docker-hosts.ts`, timeout-bounded like `checkRemoteTmuxAvailable`'s 15s, `IS_TEST_MODE` no-op):
+
+```
+docker info --format '{{json .}}'                                  # server up, CgroupVersion, rootless, OS (Desktop detect), cap-delegation
+docker image inspect <image> --format '{{.Id}}'                    # image PRESENT (no auto-pull)
+docker run --rm --pull=never <image> sh -lc 'command -v tmux'      # tmux-in-image gate (hard prerequisite), only if image present
+```
+
+`checkDockerAvailable()` returns `{ ok, engine, rootless, isDesktop, cgroupV2, capsEnforced }` (parse `SecurityOptions` for `name=rootless`, `CgroupVersion`, delegation, and Server OS for Desktop). `checkDockerTmuxAvailable(host)` returns a structured result with a user-facing error and correct install hint (NOT `npm install -g`; the hint is "build/pull the base image" for a missing image and "install docker or podman" for a missing engine).
+
+IN-CONTAINER CLI VERSION (fixing the #154 wheel-forwarding regression): the raw plan skipped the LOCAL `cliVersion` probe for docker (correct, since it reports the HOST claude) but left `cliVersion` undefined, which disables trackpad wheel-forwarding. Instead, for docker sessions Codeman runs an IN-CONTAINER probe `docker exec <container> claude --version` (bounded, `IS_TEST_MODE` no-op) and feeds THAT into `cliVersion`. This also means a stale baked CLI is visible; combined with the rebuild-cadence in user-decision 2, agents are not silently pinned to an old claude.
+
+## 5. Export / Import
+
+EXPORT is a concurrency-bounded job (reuse `runWithConversionLimit` from `document-conversion-limiter.ts` so N simultaneous exports cannot fork-bomb the host). Route `POST /api/docker-cases/:name/export`.
+
+Preconditions (the consistency and leak risks the critic caught):
+- Sealed guard: if `mountCredentials:false`, full-image export is REFUSED unless the caller explicitly opts into the pre-commit scrub (Key decision 2). Workspace-only export is always allowed.
+- Quiesce + free-space: require the session idle, then `docker pause` the container spanning BOTH the workspace tar AND the commit so the two artifacts are mutually consistent (the raw plan paused only the commit, leaving the bind-mount tar to run against a mid-write agent). Before any heavy step, precheck free space in the exports dir and in `/var/lib/docker`; if below `DOCKER_EXPORT_MIN_FREE_BYTES`, refuse with a clear error (a full `/var/lib/docker` wedges the daemon and breaks EVERY session on the host).
+
+Steps (all cleanup in try/finally so a mid-way failure never orphans an intermediate image or leaves the container paused):
+
+1. `docker commit -c 'LABEL codeman.exported=1' codeman-case-<slug> codeman/export-<slug>:<ts>` (unique tag per export defeats the stale-image trap). Optional pre-commit scrub in sealed mode as above; also blank instance-specific committed env (`-c 'ENV CODEMAN_API_URL='` etc.) so the image carries no stale host references.
+2. `docker save codeman/export-<slug>:<ts> | gzip` streamed in fixed 8192-byte chunks to `~/.codeman/docker-exports/<slug>-<ts>.image.tar.gz`. Uses `docker save` (layers + repo:tag + CMD), never `docker export` (flat rootfs), so restore is a trivial `docker load`.
+3. `tar --numeric-owner -C <hostWorkspacePath> -czf <slug>-<ts>.workspace.tar.gz .` while paused (the bind-mounted workspace is NOT in the image, so it travels separately and consistently).
+4. Write `manifest.json`: schema version, caseName, image tag, engine, containerWorkdir, resource/network config, codeman version, base-image digest, createdAt, per-member sha256, `mountCredentials`, and `secretFree` (true only for convenient-mode or scrubbed-sealed exports).
+5. `docker rmi codeman/export-<slug>:<ts>` in the `finally` (delete the intermediate committed image regardless of success), then `docker unpause`.
+
+The three files are wrapped in one bundle `<slug>-<ts>.codeman-container.tgz` and offered as a downloadable artifact through the existing file-routes streaming + attachment-registry handoff.
+
+Retention / disk budget (user-decision 3): `docker-exports/` is capped at `DOCKER_EXPORT_KEEP` most-recent bundles with an auto-prune on each new export, plus the free-space precheck above. Workspace scrub: the WORKSPACE tar gets a scan/warn pass for agent-created `.env` / `.git/credentials` (a distinct leak channel from container creds). A lighter "workspace-only" export (just the workspace tar, no commit/save) is the fast default for 24h+ runs; full-image is the explicit heavier option (user-decision 7 in the original list, now decision on the default button below).
+
+What travels: the baked toolchain image plus any in-image writes, and the workspace tar. What does NOT travel: bind-mounted credentials (physically excluded from commit) and anything that lived only in a bind mount. Secret-free by construction in convenient mode, and enforced (refuse-or-scrub) in sealed mode.
+
+IMPORT `POST /api/docker-cases/import` (untrusted-bundle containment, the traversal/overwrite risk): stream the uploaded bundle, validate every manifest checksum BEFORE any extraction or load. Extract the workspace tar with `tar --no-absolute-names -C <fresh dir>` PLUS per-entry validation rejecting any member whose normalized path escapes the destination (leading `/` or `..` components). `gunzip | docker load` the image, then RE-TAG the loaded image id into a quarantined namespace `codeman/imported-<slug>:<ts>` and NEVER allow the load to overwrite `codeman/agent:base` or any pre-existing tag (capture the loaded id, ignore the bundle's repo:tag). Create a NEW `DockerCase` pointing at the quarantined image with THIS host's mounts/creds and the manifest's resource/network config, and recreate the container hardened (cap-drop ALL, no-new-privileges, non-root, `--pull=never`, CMD overridden to `sleep infinity`). The destination supplies its own login, so credentials never cross machines. Plus `GET /api/docker-exports` (list) and `DELETE /api/docker-exports/:filename`, all behind Codeman's existing auth / loopback-default / host-guard / Origin-CSRF stack.
+
+## 6. Codeman integration (file-by-file, mirroring the remote-SSH feature)
+
+- `src/types/session.ts`: add `DockerCommandMode`, `DockerEngine`, `DockerNetworkMode`, `DockerResourceLimits`, `DockerHost`, `DockerCase`, `SessionDocker` (Section 3). Add `docker?: SessionDocker` to `SessionState` after line 219. SessionMode (line 44) UNCHANGED.
+- `src/mux-interface.ts`: add `docker?: SessionDocker` to `MuxSession` (38), `CreateSessionOptions` (81), `RespawnPaneOptions` (105).
+- `src/docker-hosts.ts` (NEW, direct mirror of `src/remote-hosts.ts`): `readDockerHosts`/`writeDockerHosts`/`readDockerCases`/`writeDockerCases` (via `dataPath`, including `lastClaudeSessionId` read/write), `defaultDockerCommandForMode` (mirror line 60), `dockerDisplayPath` (`container:/path`, mirror `remoteDisplayPath` at 205), `toSessionDocker(host, case)` (mirror `toSessionRemote` at 212), `buildDockerBaseArgs`/`buildDockerCreateArgs` (per-engine uid/userns branch), `hostGatewayAlias(engine)`, `containerApiUrl(processApiUrl, engine)` (scheme+port-preserving, unit-tested), `checkDockerAvailable`/`checkDockerTmuxAvailable`/`probeDockerCliVersion` (15s-bounded, `IS_TEST_MODE` no-op), a config-hash helper for drift, its own POSIX `shellescape` copy (mirror line 83). `const IS_TEST_MODE = !!process.env.VITEST;` gates every real `docker` invocation.
+- `src/tmux-manager.ts`: add `DOCKER_TMUX_SOCKET`, `dockerTmuxSessionName`, `buildDockerLaunchCommand` (resume-aware, image-check, env-prime), `buildDockerKillCommand` (Section 4). Extend the two `fullCmd` ternaries (1276, 1524) and the two `launchCmd` cd-skips (1327, 1542). Add `killSession` Strategy 3c after 1719. Ensure `reconcileSessions` (~1800-1815) does NOT hard-delete docker sessions on local-tmux death (recovery relaunch path).
+- `src/session.ts`: add `_docker?: SessionDocker` field (mirror `_remote` at 403), constructor arg (477), assignment (550). Thread `docker: this._docker` and `resumeSessionId: this._claudeSessionId` into BOTH `createSessionOptions` and `respawnPaneOptions` in `startInteractive` (1352/1370) and the second path (1740/1750). Emit `docker: this._docker` in `toState()` (1010). Replace the LOCAL cliVersion probe at 1320 for docker with the IN-CONTAINER `probeDockerCliVersion` (do not merely skip it). Extend `resolveMuxAttachCwd(workingDir, remote, docker)` (215) to return `/tmp` when `docker` is set. On claudeSessionId capture, persist it to the owning `DockerCase.lastClaudeSessionId`.
+- `src/web/server.ts`: in `restoreMuxSessions` (2160), add `docker: muxSession.docker ?? savedState?.docker` to the `new Session({...})` call (2195-2216), and skip docker in the same `isExternalCliMode`/Ralph recovery guards as remote. Register the instance-scoped boot reaper to run AFTER docker-cases load and AFTER `restoreMuxSessions`. Ensure `CODEMAN_API_URL` derivation reads the SAME `process.env.CODEMAN_API_URL` the server sets at ~2000.
+- `src/web/schemas.ts`: add `DockerHostSchema` and `DockerCaseLinkSchema` (below). The three mode enums (177/373/705) and `QuickStartSchema` (368) UNCHANGED (docker resolves by `caseName` lookup like remote).
+- `src/web/routes/session-routes.ts`: import the docker helpers from `../../docker-hosts.js`. Add a docker branch in `/api/quick-start` parallel to the remote branch (1686-1720): `readDockerCases` -> find by `caseName` -> `readDockerHosts` -> find by `hostId`; reject `envOverrides`/`effort`/`codexConfig`/`geminiConfig`/`openCodeConfig` (but ACCEPT `modelOverride`, which flows via scaffolded `settings.local.json`); run `checkDockerAvailable` + `checkDockerTmuxAvailable` (image-present, engine, caps-enforced); surface `capsEnforced:false` and Desktop notes; set `casePath = dockerCase.hostWorkspacePath` (REAL host dir), `docker = toSessionDocker(host, dockerCase)`, and seed `resumeSessionId` from `dockerCase.lastClaudeSessionId` when `resumeOnStart`. Extend the LOCAL-availability and local-spawn guards (around 1796/1810) to `!remote && !docker`, but DO NOT extend the workspace-scaffolding guard (~1776, `writeHooksConfig`/`updateCaseModel`), which MUST run for docker. Pass `docker` into `new Session` (1847); `autoConfigureRalph` (1853) gated on `!docker`. Add `docker: m.docker !== undefined ? true : undefined` to the unified harvest (2313).
+- `src/web/routes/case-routes.ts`: import the docker read/write/check helpers + schemas. Add a docker listing loop in `GET /api/cases` (mirror 94-119, `location: 'docker'`, `docker: {...}` via `dockerDisplayPath`). Add `/api/docker-hosts` GET/POST/PUT/DELETE (mirror 168-204) and `POST /api/cases/docker-link` (mirror 206-232; run `checkDockerAvailable`/`checkDockerTmuxAvailable` at link time; broadcast `CaseLinked` with `type: 'docker'`). Add a docker-unlink branch to `DELETE /api/cases/:name` (mirror 288-296; `docker rm -f`; broadcast `CaseDeleted` `type: 'docker-unlinked'`). Add the docker branch to single-case `GET` (mirror 358-368). Add `POST /api/docker-cases/:name/export`, `/import`, `GET/DELETE /api/docker-exports`, and a `POST /api/docker-cases/:name/recreate` (drift confirm) per Sections 4 and 5.
+- `src/web/sse-events.ts` + `src/web/public/constants.js`: reuse `CaseLinked`/`CaseDeleted` for CRUD. Add `docker:exportProgress`, `docker:exportComplete`, `docker:importComplete`, `docker:configDrift`, and `docker:containerError` to BOTH registries (kept in sync per CLAUDE.md).
+- Frontend `src/web/public/index.html` (~1831): add a Docker `modal-tab-btn` next to Remote; add a `#case-docker` panel mirroring `#case-remote` with `dockerCaseName`, `dockerHostWorkspacePath`, `dockerContainer`, `dockerImage`, `dockerHostId`, and an Advanced `<details>` for network mode, resource caps, `mountCredentials`, `resumeOnStart`, and remote daemon. Surface a "scaffolds .claude into this host dir" note (user-decision 4) and a "resource caps advisory on this engine" warning when `capsEnforced:false`.
+- Frontend `src/web/public/session-ui.js`: `formatCasePickerLabel` (48) + `buildCasePickerOptions` (71-73) handle `location === 'docker'` (`name @ container`, add container/image to the search haystack); `resetCaseModalFields` (~1514) add a `dockerFields` array; `switchCaseModalTab` (1573/1580/1597) handle `'case-docker'`; `submitCaseModal` add the docker branch; new `linkDockerCase()` (mirror `linkRemoteCase` at 1689) POSTing `/api/docker-hosts` then `/api/cases/docker-link`, sending omitted optionals as `undefined` (spread `...(x ? {x} : {})`, never `null`, per the Zod `.optional()`-rejects-null gotcha); `runClaude` (520) / `runShell` (702) extend the `location === 'remote'` routing to also match `'docker'`; `runOpenCode`/`runCodex`/`runGemini` (792/846/900) make the `isRemote` checks `isRemoteOrDocker` so local status probes are skipped. In the session-options Summary tab, note that `effort` is inert for docker (rejected) while `model` IS honored via `settings.local.json`.
+- Frontend `src/web/public/panels-ui.js` (425-426): add `caseItem?.docker?.path`/`container` to the case-search fields.
+
+Schemas (`src/web/schemas.ts`), mirroring `RemoteHostSchema` (299) / `RemoteCaseLinkSchema` (351):
+
+```ts
+export const DockerHostSchema = z.object({
+  id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  label: z.string().min(1).max(100),
+  engine: z.enum(['docker', 'podman']).optional(),
+  image: z.string().min(1).max(512).regex(/^[a-zA-Z0-9][\w./:@-]*$/, 'Invalid image ref').regex(NO_SHELL_META),
+  daemonHost: z.string().max(512).regex(NO_SHELL_META, 'Invalid daemon host').optional(),
+  context: z.string().max(128).regex(/^[a-zA-Z0-9._-]+$/, 'Invalid context').optional(),
+  network: z.enum(['bridge', 'none', 'custom']).optional(),
+  networkName: z.string().max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/).optional(),
+  resources: z.object({
+    memory: z.string().regex(/^\d+[bkmg]?$/i).optional(),
+    cpus: z.string().regex(/^\d+(\.\d+)?$/).optional(),
+    pidsLimit: z.number().int().positive().max(100000).optional(),
+    nofile: z.string().regex(/^\d+:\d+$/).optional(),
+    shmSize: z.string().regex(/^\d+[bkmg]?$/i).optional(),
+  }).strict().optional(),
+  mountCredentials: z.boolean().optional(),
+  hooksEnabled: z.boolean().optional(),
+  resumeOnStart: z.boolean().optional(),
+  commands: RemoteCommandOverridesSchema, // reuse the shared shape
+  extraCreateArgs: z.array(z.string().min(1).max(1024).regex(NO_SHELL_INJECTION).refine(noCommandSubstitution)).max(32).optional(),
+  extraExecArgs: z.array(z.string().min(1).max(1024).regex(NO_SHELL_INJECTION).refine(noCommandSubstitution)).max(32).optional(),
+});
+
+export const DockerCaseLinkSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
+  hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  hostWorkspacePath: z.string().min(1).max(2000).regex(/^\//, 'Path must be absolute').regex(NO_SHELL_META, 'Invalid characters in workspace path'),
+  containerWorkdir: z.string().min(1).max(2000).regex(/^\//).regex(NO_SHELL_META).optional(),
+  container: z.string().min(2).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name').optional(),
+});
+```
+
+`NO_SHELL_META` (rejects `$`/backtick, schemas.ts:297) is REQUIRED on `image`, `hostWorkspacePath`, `containerWorkdir`, and `container`, because all four reach the outer `bash -c "..."` double-quote layer where `$(...)`/backtick re-expose, exactly the reason `remotePath`/`identityFile` use it. `--privileged` and any `-v /var/run/docker.sock` are structurally unrepresentable (never emitted by the builder, never accepted by the schema).
+
+## 7. Security model
+
+- Hardening flags on every create: `--cap-drop ALL`, `--security-opt no-new-privileges` (NOT auto-set by rootless Docker or Podman, so always explicit), the uid/userns branch of Key decision 6 (never container-root; workspace files stay host-owned and HOME stays writable via GID 0), `--pids-limit` (fork-bomb guard), `--memory` with `--memory-swap == --memory` (real OOM cap), `--ulimit nofile`, `--init`, `--pull=never`. NEVER `--privileged`, NEVER mount the docker socket into the agent container. `--storage-opt size=` is emitted ONLY after the probe confirms overlay2-on-xfs-pquota or btrfs (the AICE-class silently-ignored trap); otherwise it is omitted and the UI does not advertise a size cap. Resource caps are advertised as ENFORCED only when the probe reports `capsEnforced:true`; under non-delegated rootless they are labeled advisory (user-decision 6).
+- Engine: prefer whichever the probe finds, Podman-rootless first for security (a container-root breakout lands as an unprivileged host user). Rootless bind-mount ownership uses `--userns=keep-id` (Podman) vs `--user <hostUid>:0` (Docker), so real per-engine branching lives in `buildDockerCreateArgs`. Docker Desktop takes its own uid path (Key decision 6).
+- Blast radius (the combined-posture the critic asked to surface, user-decision 5): the default convenient profile mounts an arbitrary host workspace dir RW (host-owned, mirrored path) AND host `~/.claude`/`~/.codex`/`~/.gemini`/`~/.config/gcloud`/`~/.config/opencode` RW into a NETWORK-ENABLED container. Container-run agent code can therefore read/modify those host trees and reach the network simultaneously. This is still a strict improvement over today's on-host skip-permissions execution, but the user must accept the combined posture explicitly; the sealed profile plus `network:none` is the mitigation for genuinely untrusted work.
+- Secret handling: creds arrive ONLY as bind-mounted files (default) or exec-time NAME-ONLY `--env` (codex/gemini keys), NEVER as create-time `-e` and NEVER as an image layer. Sealed-mode export is refuse-or-scrub (Section 5), closing the sealed-leak inversion.
+- CLAUDE.md "Multi-CLI prefix discipline": the exec-time name-only env is restricted to the CLI-specific keys per mode (Claude: none with OAuth mount; Codex: `OPENAI_API_KEY`/`CODEX_API_KEY`; Gemini: `GEMINI_API_KEY`/`GOOGLE_*`), never a blanket forward. `envOverrides` is rejected for docker, so the `ALLOWED_ENV_PREFIXES` allowlist is not widened.
+- hook-secret: bind-mounted read-only, referenced via `CODEMAN_HOOK_SECRET_FILE` (a path, non-secret); the secret bytes never enter env or the image. Both `host.docker.internal` and `host.containers.internal` are added to the host-guard allowlist so the in-container hook curl's Host header passes on either engine.
+- Host guard / instance isolation: the in-container tmux socket (`codeman-docker`) and name (`codeman-dkr-<id8>`) deliberately FAIL a container-internal Codeman's `SAFE_MUX_NAME_PATTERN`, so a nested Codeman never adopts our session (unit-asserted). The boot reaper is instance-scoped by the `codeman.instance` label so a beta never reaps prod. Any remote-daemon (`-H`/`--context`) mode is host-root-equivalent and stays strictly behind the existing auth/loopback/host-guard/Origin-CSRF stack.
+- Import containment: untrusted bundles are checksum-validated, extracted with traversal guards, and loaded into a quarantined image namespace (never overwriting the base image), then run with the same hardening.
+
+## 8. Phased implementation (branch: `feat/docker-session-mode`)
+
+Each phase is independently testable; per CLAUDE.md, end-to-end test in the real env before COM. All new docker IO paths carry `const IS_TEST_MODE = !!process.env.VITEST;` and no-op under it; the pure command builders are tested directly.
+
+- Phase 0: base image + engine probe. Author `docker/agent.Dockerfile` (OpenShift arbitrary-uid HOME) and `scripts/build-agent-image.mjs` (build or pull the base image; digest recorded). Add `checkDockerAvailable`/`checkDockerTmuxAvailable`/`containerApiUrl`/`hostGatewayAlias` (IS_TEST_MODE no-op) and `GET /api/docker/status`. Test: probe stub returns available/caps/Desktop flags under VITEST; `containerApiUrl` preserves scheme+port and swaps host per engine; status route returns the envelope.
+- Phase 1: types + storage + schemas. Add all types (Section 3), `src/docker-hosts.ts`, `DockerHostSchema`/`DockerCaseLinkSchema`. Test: `docker-hosts.test.ts` (round-trip incl. `lastClaudeSessionId`, display path, config-hash stability); `docker-exec-options.test.ts` (schema rejects `$`/backtick in image/workdir/container).
+- Phase 2: tmux-manager builders. Add `DOCKER_TMUX_SOCKET`, `dockerTmuxSessionName`, `buildDockerLaunchCommand` (resume-aware, image-check, env-prime), `buildDockerKillCommand`; wire the two ternaries + two cd-skips + Strategy 3c; harden `reconcileSessions` against docker hard-delete. Test (pure strings): adopt-proof name fails `SAFE_MUX_NAME_PATTERN`; image-check precedes create; `new-session -A` idempotent; resume flag present only when a resume id is passed; `--pull=never` present; instance label present; escaping survives `bash -c` -> `docker exec` -> `sh -lc` -> tmux WITH a host workspace path containing spaces.
+- Phase 3: session.ts + mux + recovery. Add `_docker` + `resumeSessionId` threading, in-container cliVersion probe, `resolveMuxAttachCwd`, mux-interface fields, `restoreMuxSessions` passthrough, instance-scoped reaper wiring, claudeSessionId -> `DockerCase.lastClaudeSessionId` persistence, unified flag. Test: `toState()` emits docker; a persisted docker session round-trips through mux/state; a relaunch injects the persisted resume id (mock mux); reaper only targets this instance's orphaned containers.
+- Phase 4: routes + first real e2e. case-routes CRUD + listing + drift-recreate; session-routes quick-start branch (scaffolding RUNS, local-availability guards skip, model accepted, effort/config rejected). Manual e2e on a real docker host: docker-host create -> docker-link -> quick-start; confirm the pane runs `claude` in the container, files land host-owned, a Codeman restart reattaches the SAME live agent, and a `docker stop` followed by relaunch RESUMES the conversation.
+- Phase 5: hooks connectivity + installation. host-gateway (per engine), derived `CODEMAN_API_URL`, hook-secret mount, `CODEMAN_SESSION_ID`/`CODEMAN_MUX` exec-env + tmux setenv, host-guard allowlist, and the scaffolding write into the real workspace. Manual e2e: trigger a permission prompt from inside the container and confirm it surfaces; verify hook payloads carry the right session id. If deferred, ship docker as explicitly hook-degraded and verify output-based idle detection through the docker-exec PTY.
+- Phase 6: export/import + GC + disk safety. quiesce+pause span, free-space precheck, commit+save+gzip + workspace tar + manifest + streaming download; sealed-mode refuse-or-scrub; retention/auto-prune; import with checksum validation + traversal guard + quarantined re-tag; drift-recreate; boot reaper; `runWithConversionLimit` cap; `docker rmi` in finally. Manual e2e: export, `docker load` on a second machine (or fresh case), import, confirm toolchain + workspace restored and NO creds present; attempt a sealed full-image export and confirm it is refused-or-scrubbed; attempt a `../` bundle and confirm it is rejected.
+- Phase 7: frontend. Docker tab, `linkDockerCase`, run wiring, case-picker labels, panels search, caps-advisory + scaffold-warning + effort-inert notes. Verify with Playwright (`waitUntil: 'domcontentloaded'`, 3-4s settle) that the Docker tab renders and a linked docker case appears in the picker.
+- Phase 8: docs + COM. Update CLAUDE.md (a "Docker cases" Key Pattern paragraph mirroring remote-SSH, plus the new state files, routes counts, and the resume/durability model), `docs/docker-cases.md`, then COM per the standard flow.
+
+## 9. Test plan
+
+- Unit (pure, CI-safe, mirror `test/remote-hosts.test.ts` / `test/remote-ssh-options.test.ts`):
+  - `test/docker-hosts.test.ts`: storage round-trip (incl. `lastClaudeSessionId`), `dockerDisplayPath`, `defaultDockerCommandForMode`, `toSessionDocker`, `containerApiUrl` (http/https, custom port, docker vs podman gateway), config-hash stability/drift, `buildDockerCreateArgs` flag ordering (cap-drop/no-new-privileges/memory==memory-swap/instance-label/`--pull=never` present; host/privileged/socket absent; per-engine uid vs `--userns=keep-id`).
+  - `test/docker-exec-options.test.ts`: `buildDockerLaunchCommand`/`buildDockerKillCommand` string shape and escaping through `bash -c` -> `docker exec` -> `sh -lc` -> tmux, including a workspace path with spaces; resume flag present only with a resume id; image-presence check precedes create; `dockerTmuxSessionName` fails `SAFE_MUX_NAME_PATTERN`; schema rejects `$`/backtick in image/workdir/container/name; `linkDockerCase`-shaped bodies with omitted optionals validate (no `null` on the wire).
+  - Probe no-op: `checkDockerAvailable`/`checkDockerTmuxAvailable`/`probeDockerCliVersion` return canned values under VITEST and never spawn.
+- Integration (route tests via `app.inject()`, docker no-op'd): `/api/docker-hosts` CRUD; `/api/cases/docker-link` dup-check + broadcast; `GET /api/cases` includes the docker case with `location: 'docker'`; `/api/quick-start` docker branch rejects `envOverrides`/`effort`/config but ACCEPTS `modelOverride`, runs the workspace-scaffolding path, and constructs a session with `docker` set + seeded resume id; `DELETE /api/cases/:name` docker-unlink; export refuse-or-scrub for sealed; import traversal rejection; reaper instance-scoping (label filter). Pick a unique port only if a live-server test is added (search `const PORT =`; 3150+).
+- Manual end-to-end (real docker daemon, the mandatory "always end-to-end test" gate): build the base image; link a docker case; quick-start `claude`; verify OAuth via the mounted `~/.claude`, transcript correlation (subagent/workflow watchers show the session), host-owned files, and a working permission-prompt hook; reattach after a Codeman PROCESS restart (SAME live agent); `docker stop` then relaunch and confirm conversation RESUME; reboot-equivalent (daemon restart) and confirm boot recovery recreates+resumes; change the host's memory/image and confirm the drift-recreate prompt fires; export (convenient) and confirm the tar `docker load`s with no creds; attempt a sealed full-image export and confirm refuse-or-scrub; import into a fresh case; delete the case and confirm `docker rm -f` plus instance-scoped reaper GC; confirm a docker-down state surfaces a docker-specific error and does NOT trip the generic PTY-exit breaker.
+
+## 10. Open decisions for the user
+
+1. Credential + blast-radius posture (combined). Convenient default bind-mounts host `~/.claude` etc. RW AND an arbitrary host workspace RW into a network-enabled container, so container-run agent code can read/modify those host trees and reach the network at the same time. Recommended: convenient default plus a per-host SEALED opt-in (`mountCredentials:false` + `network:none`) for untrusted work. Please confirm you accept the combined arbitrary-workspace-plus-egress-plus-host-creds posture for the default profile (it is still a net improvement over today's on-host skip-permissions execution).
+2. Base image ownership, registry, and freshness. The `codeman/agent:base` placeholder implies a Docker Hub org the project may not own. Pick the real registry/namespace (GHCR under the repo is the natural fit), decide digest pinning, and set a REBUILD CADENCE so agents are not stuck on a stale baked `claude` (the in-container version probe surfaces staleness, but something must trigger rebuilds). Choose: pull a pinned published image, build locally on first use via `scripts/build-agent-image.mjs`, or both.
+3. Container CWD strategy. Mirror the host workspace path inside the container (recommended: makes transcript projHash correlate, file features and resume capture work) vs a fixed `/workspace` (simpler mount, breaks watcher correlation). Please confirm the mirror approach.
+4. Hooks in the MVP AND workspace scaffolding. Making docker hooks fire requires WRITING `.claude/settings.local.json` (and the CLAUDE.md scaffold) into the user's REAL linked host directory, a behavioral shift from "link a dir" to "link and scaffold a dir." Choose: wire hooks + scaffolding now (Phase 5, recommended, and it also enables the model picker), or ship docker as explicitly hook-degraded (no permission prompts / hook-idle) for v1 and add later. Confirm you are OK with Codeman mutating the linked host workspace.
+5. Session-kill teardown and RESUME (reframed honestly). `docker stop` on session kill is not merely "free RAM vs instant reattach": it destroys the in-container live agent, and the conversation survives ONLY because the next launch runs `--resume` from the bind-mounted transcript. Choose: keep the container running (costs RAM, preserves the exact live in-flight agent) vs stop and rely on `--resume` (frees RAM, may lose uncommitted in-flight tool state). Case-delete always `docker rm -f`.
+6. Rootless enforcement posture. Under rootless without cgroup-v2 systemd delegation, `--memory`/`--cpus`/`--pids-limit` are SILENTLY ignored. Choose: REQUIRE delegation (refuse to link a host that cannot enforce caps) or ship-with-warning ("resource caps are advisory on your engine"). The probe reports `capsEnforced` either way.
+7. Default resume behavior. Should a re-linked or re-run docker case default to resuming its last conversation (`resumeOnStart:true`, using `DockerCase.lastClaudeSessionId`) rather than starting clean? This is the crux of making the durability story real and is the recommended default, but it changes user-visible behavior (a new session in an existing case continues the prior conversation).
+8. Export defaults and disk budget. Default export button: workspace-only (fast, small, files-only, recommended for 24h+ runs) vs full-image (reproducible env, multi-GB). Also set the retention cap (max retained exports), the auto-prune policy, and the free-space threshold below which export is refused (a full `/var/lib/docker` breaks EVERY session on the host, not just docker ones).
+9. Remote docker daemon (`-H ssh://...` / `--context`). Support in the MVP (composes with remote hosts, adds host-root trust surface) or local-daemon-only first.
+10. Podman parity depth. Full `--userns=keep-id` plus Quadlet boot-persistence, or Docker-first with Podman as best-effort and boot-persistence via Codeman's idempotent create-if-missing only. Note the podman host alias is `host.containers.internal`, already handled per engine.

docs/docker-cases.md

@@ -0,0 +1,95 @@
+# Docker cases
+
+Run a case inside an **isolated Docker container** instead of directly on the host. Any number of Codeman sessions can share one container (it is scoped to the case, not the session), so a whole project lives in a sandbox with its own network, resource caps, and filesystem, and you can **export the container to move it to another machine**.
+
+Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` all work inside the container.
+
+## One-time setup: build the base image
+
+The container needs a base image with the agent toolchain (node, the CLIs, git, tmux). Build it locally once:
+
+```bash
+node scripts/build-agent-image.mjs          # builds codeman/agent:base
+# options: --engine docker|podman  --image <ref>  --no-cache
+```
+
+The image is **secret-free**: credentials are delivered at runtime (bind mounts or `docker exec --env`), never baked in, so exports never leak them.
+
+## Quickest path: one-click "Run in Docker"
+
+On the **New case → Create New** tab there's a **🐳 Run in an isolated Docker container** checkbox. Checking it alone is enough: Codeman creates the case folder in `~/codeman-cases/<name>`, spins up a hardened container with sensible defaults (auto-provisioning a shared `default` host), and starts the session inside it. No host/image/network fields to fill in.
+
+Click the checkbox's **Container settings** to optionally tweak the predefined defaults, including a **Template** picker:
+
+| Template | Memory | CPUs | GPUs |
+|----------|--------|------|------|
+| Small | 2 GB | 1 | none |
+| Medium (default) | 4 GB | 2 | none |
+| Large | 8 GB | 4 | none |
+| GPU | 8 GB | 4 | all (needs the NVIDIA container toolkit) |
+
+**Disk is elastic** — the container's storage grows automatically as data flows in; there is no fixed cap (bounded only by host disk). Any tweaked setting creates a dedicated per-case host so it never changes the shared `default`.
+
+## Create a docker case (full control)
+
+App → **New case → Docker** tab:
+
+- **Case Name** / **Workspace Path**: the workspace is a real HOST directory bind-mounted into the container at the same path. Codeman scaffolds `CLAUDE.md` + `.claude/settings.local.json` (hooks) into it, and file previews / attachments work on the real bytes.
+- **Host ID**: a reusable docker host profile (image, network, resources). Reuse the same ID across cases to share settings.
+- **Network**: `bridge` (internet on, default), `none` (fully isolated), or a `custom` bridge.
+- **Advanced**: memory / CPU caps, **Mount host credentials** (on = your existing `~/.claude` login just works; off = a sealed sandbox you log into inside the container), **Resume last conversation on relaunch**.
+
+Then run it like any case (Run Claude / Run Shell / …). The first launch creates the container (`codeman-case-<name>`); subsequent sessions attach to the same one.
+
+Equivalent API:
+
+```bash
+curl -X POST localhost:3000/api/docker-hosts -d '{"id":"local","label":"Local","image":"codeman/agent:base"}'
+curl -X POST localhost:3000/api/cases/docker-link -d '{"name":"sandbox","hostId":"local","hostWorkspacePath":"/home/you/projects/sandbox"}'
+curl -X POST localhost:3000/api/quick-start -d '{"caseName":"sandbox","mode":"claude"}'
+```
+
+## Lifecycle
+
+- **Reconnect after a Codeman restart** lands back in the same live agent (the in-container tmux survives).
+- **Container stop / host reboot** restarts the container and **resumes** the last conversation from the bind-mounted transcript. Claude sessions launch with a pinned conversation id (`--session-id <sessionId>`, with a `--resume` fallback when the transcript already exists), and the case remembers its last conversation (`lastClaudeSessionId`), so a relaunch after the container was stopped, rebooted, or recreated continues where it left off.
+- **Killing one session** only kills that session's in-container tmux session; the shared container stays up for sibling sessions.
+- **Editing the docker host config** (image, memory, network, ...) is detected on the next launch: the desired config hash is compared against the container's `codeman.confighash` label, and a mismatch refuses the launch with a "config changed, recreate?" confirm. Confirming calls `POST /api/docker-cases/:name/recreate` (refused while sessions of the case are live), which removes the container so the next launch recreates it with the new config; the workspace and the conversation survive.
+- **Deleting the case** `docker rm -f`s the container (the bind-mounted workspace on the host survives). An instance-scoped boot reaper removes containers whose case is gone.
+
+## Isolation & security
+
+Every container runs hardened: `--cap-drop ALL`, `--security-opt no-new-privileges`, non-root (`--user <hostUid>:0` so workspace files stay host-owned), `--pids-limit`, `--memory` == `--memory-swap`, `--init`. Never `--privileged`, never the docker socket. The default **convenient** profile bind-mounts host credential dirs read-write so the common login just works (creds stay on the host, never captured by `docker commit`); the **sealed** profile (`mountCredentials:false` + `network:none`) is the opt-in for genuinely untrusted work.
+
+Rootless engines without cgroup-v2 systemd delegation cannot enforce resource caps; linking such a host warns that caps are advisory.
+
+## Export / Import (move to another machine)
+
+**Export** (from the Docker tab, or `POST /api/docker-cases/:name/export`): choose
+
+- **Full image + workspace**: `docker commit` the container to an image, `docker save` it, tar the workspace, and a manifest, all into one portable `<case>-<ts>.codeman-container.tgz` (the whole toolchain, installed packages, and files). Runs in the background; you are notified when the bundle is ready.
+- **Workspace only**: just the project files (fast, small).
+
+The container is paused across the capture so the image and workspace are consistent; a full `/var/lib/docker` is guarded against with a free-space precheck; the intermediate image is always cleaned up.
+
+**Import** (`POST /api/docker-cases/import`, or the Manage tab): copy the `.tgz` onto the new machine's `~/.codeman/docker-exports/`, then import it into a new case. The manifest and per-member SHA-256 checksums are validated, the workspace tar is extracted with a path-traversal guard, and the image is `docker load`ed and **re-tagged into a quarantined namespace** (`codeman/imported-<case>:<ts>`) so it never overwrites a local tag. The destination supplies its own credentials, so nothing secret crosses machines.
+
+`GET /api/docker-exports` lists bundles; `GET /api/docker-exports/:filename` downloads one; `DELETE` removes one.
+
+## Hooks require the server to be reachable from the container
+
+In-container hooks (permission events, hook-based idle/stop/task notifications) POST to `CODEMAN_API_URL`, which is derived as `https://host.docker.internal:<port>` (`host.docker.internal` → the docker bridge gateway, e.g. `172.17.0.1`, via `--add-host …:host-gateway`). For that callback to succeed, the Codeman server must be **listening on an interface the container can reach**.
+
+- If Codeman binds **loopback-only** (`127.0.0.1`, the default and the production systemd config), a container reaching `172.17.0.1:<port>` cannot connect, so by default **in-container hooks do not fire**. The session still works fully: idle/stop detection falls back to **output-based** detection through the `docker exec` PTY (which always works), and claude runs with `--dangerously-skip-permissions` so there are no permission prompts to forward anyway.
+- **To enable in-container hooks on a loopback-only server, set `CODEMAN_DOCKER_BRIDGE_HOOKS=1`** (env). Codeman then starts a SECOND listener bound to the docker bridge gateway (`172.17.0.1`, auto-detected; override with `CODEMAN_DOCKER_BRIDGE_HOST`) that serves **only the hook endpoints** (`/api/hook-event`, `/api/status-telemetry`) and delegates them into the same secret-gated pipeline. The bridge is host-internal (containers + host, not the LAN), and every other path returns `403`, so this does not widen your network exposure. Add `Environment=CODEMAN_DOCKER_BRIDGE_HOOKS=1` to the systemd unit and restart.
+- Alternatively, bind `0.0.0.0` **with `CODEMAN_PASSWORD` set** (exposes on the LAN too).
+
+The host-gateway mapping, `CODEMAN_API_URL` derivation, host-guard allowlist, and hook-secret mount are all wired correctly; `CODEMAN_DOCKER_BRIDGE_HOOKS` closes the last gap for loopback-only servers.
+
+## Notes & limits
+
+- Requires Docker (or Podman) with a reachable daemon; tmux must be present in the base image (a hard prerequisite, probed at link time).
+- Per-session `envOverrides` / `effort` / per-CLI config are rejected for docker cases (they do not cross into the container); configure the container via the docker host's per-mode command override instead.
+- macOS Docker Desktop takes a dedicated uid path (the baked image uid; memory caps are subject to the VM ceiling).
+
+Design + rationale: [`docker-cases-plan.md`](./docker-cases-plan.md).