@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/types.mjs

@@ -0,0 +1,414 @@
+/**
+ * Shared data shapes for the agent-board store. JSDoc typedefs (consumed by the TS
+ * extension via `allowJs`) plus the canonical state vocabularies as runtime constants.
+ */
+
+/** Semantic (task) state of a row. @typedef {"queued"|"working"|"needs_input"|"idle"|"holding"|"completed"|"failed"|"stopped"} SemanticState */
+/** Process/liveness state. @typedef {"alive"|"exited"} ProcessState */
+/** PTY host mode. @typedef {"json-runner"|"pty"} HostMode */
+/** PTY host liveness. @typedef {"starting"|"alive"|"stopping"|"exited"|"failed"} HostState */
+/** How a run was kicked off. @typedef {"dispatch"|"reply"|"plan"|"plan_change"|"plan_approval"} RunKind */
+/** Worktree isolation mode for a row. @typedef {"off"|"worktree"} WorktreeMode */
+/** Diagnostic severity. @typedef {"info"|"warn"|"error"} DiagnosticLevel */
+/** Diagnostic event source. @typedef {"runner"|"host"|"service"|"queue"|"steering"|"evidence"|"store"} DiagnosticSource */
+/** Evidence outcome. @typedef {"unknown"|"in_progress"|"ready"|"needs_input"|"failed"|"stopped"|"queued"|"working"|"idle"|"holding"|"completed"} EvidenceOutcome */
+/** Command kind. @typedef {"test"|"build"|"lint"|"git"|"install"|"other"} EvidenceCommandKind */
+/** Command status. @typedef {"started"|"passed"|"failed"|"unknown"} EvidenceCommandStatus */
+/** File change action. @typedef {"edited"|"written"|"deleted"|"unknown"} EvidenceFileAction */
+/** Follow-up kind. @typedef {"reply"|"plan_request"|"plan_approval"|"plan_change"} FollowUpKind */
+/** Follow-up status. @typedef {"queued"|"claimed"|"completed"|"failed"|"cancelled"} FollowUpStatus */
+/** Steering state. @typedef {"none"|"plan_requested"|"awaiting_approval"|"approved"|"changes_requested"|"executing_approved_plan"} SteeringModeState */
+/** Dashboard auto-state bucket. @typedef {"needs_input"|"in_progress"|"done"} AutoStateKind */
+/** Auto-state classifier source. @typedef {"model"|"heuristic"} AutoStateSource */
+/** Auto-state classifier confidence. @typedef {"high"|"medium"|"low"} AutoStateConfidence */
+
+/**
+ * LLM/heuristic classification of the latest assistant turn.
+ * @typedef {Object} AutoStateClassification
+ * @property {number} version
+ * @property {AutoStateKind} kind
+ * @property {SemanticState} semanticState
+ * @property {AutoStateConfidence} confidence
+ * @property {AutoStateSource} source
+ * @property {string} reason
+ * @property {string|null} question
+ * @property {number} classifiedAt
+ * @property {number|null} lastAgentActivityAt
+ * @property {string} textHash
+ */
+
+export const SEMANTIC_STATES = /** @type {const} */ ([
+	"queued",
+	"working",
+	"needs_input",
+	"idle",
+	"holding",
+	"completed",
+	"failed",
+	"stopped",
+]);
+
+export const PROCESS_STATES = /** @type {const} */ (["alive", "exited"]);
+
+/** Order rows are grouped/shown in the dashboard (most-actionable first). */
+export const GROUP_ORDER = /** @type {const} */ ([
+	"queued",
+	"working",
+	"needs_input",
+	"idle",
+	"holding",
+	"completed",
+	"failed",
+	"stopped",
+]);
+
+/** Human labels for group headers. @type {Record<SemanticState,string>} */
+export const GROUP_LABELS = {
+	needs_input: "Needs answer",
+	working: "Running",
+	queued: "Queued",
+	failed: "Failed",
+	completed: "Done",
+	idle: "Needs instructions",
+	holding: "On hold",
+	stopped: "Stopped",
+};
+
+/**
+ * Stable row metadata (`meta.json`).
+ * @typedef {Object} ViewMeta
+ * @property {number} version
+ * @property {string} id
+ * @property {string} name
+ * @property {string} cwd               Working dir the worker runs in (repo or worktree path).
+ * @property {string} repoCwd           Original repo dir requested at dispatch (== cwd unless worktree).
+ * @property {string|null} repoRoot     Git repo root, if any.
+ * @property {string} sessionFile        Managed Pi session JSONL path.
+ * @property {number} createdAt
+ * @property {number} updatedAt
+ * @property {boolean} pinned
+ * @property {"pi-session"} kind
+ * @property {string|null} defaultModel
+ * @property {"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|null} defaultThinking
+ * @property {WorktreeMode} worktreeMode
+ * @property {string|null} worktreePath
+ * @property {boolean} writeCapable      Whether this session may mutate files (default true).
+ * @property {boolean} archived          Soft-deleted from the dashboard (data preserved).
+ * @property {"agent-board"} source
+ */
+
+/**
+ * Derived dashboard state for a row (`state.json`).
+ * @typedef {Object} ViewState
+ * @property {number} version
+ * @property {string} viewId
+ * @property {string|null} currentRunId
+ * @property {SemanticState} semanticState
+ * @property {ProcessState} processState
+ * @property {string} summary
+ * @property {number} lastActivityAt
+ * @property {number} updatedAt
+ * @property {boolean} needsInput
+ * @property {boolean} hasError
+ * @property {string} latestAssistantPreview
+ * @property {{name:string, path:string|null}|null} latestTool
+ * @property {string|null} question
+ * @property {Array<{toolCallId:string, question:string}>} pendingQuestions
+ * @property {string|null} error
+ * @property {number|null} lastVisitedAt
+ * @property {number|null} lastAgentActivityAt Timestamp of the latest assistant reply shown in the row.
+ * @property {ReviewSummary} [review] Compact collected-evidence summary.
+ * @property {DiagnosticSummary} [diagnostics] Compact diagnostics summary.
+ * @property {FollowUpSummary} [followUps] Compact queued follow-up summary.
+ * @property {SteeringSummary} [steering] Compact plan/approval steering summary.
+ * @property {CodeRefsSummary} [codeRefs] Compact issue/PR reference summary.
+ * @property {AutoStateClassification|null} [autoState] Latest automatic terminal-state classification.
+ * @property {number} [materializedRevision] Coordinator-stamped monotonic revision (issue #91). Absent on legacy rows until the View State Coordinator first materializes the view.
+ */
+
+/**
+ * Durable PTY host snapshot (`host.json`).
+ * @typedef {Object} HostStatus
+ * @property {number} version
+ * @property {string} viewId
+ * @property {HostMode} mode
+ * @property {number|null} runnerPid
+ * @property {number|null} childPid
+ * @property {string|null} socketPath
+ * @property {HostState} state
+ * @property {number} startedAt
+ * @property {number} lastSeenAt
+ * @property {number|null} endedAt
+ * @property {number|null} exitCode
+ * @property {string|null} error
+ * @property {number} cols
+ * @property {number} rows
+ * @property {number} attachedClients
+ * @property {boolean} [attachedEver] Whether any client attached to this host.
+ * @property {string|null} [instanceId] Owner/fencing token for this host launch (issue #70).
+ * @property {string|null} [configPath] Per-instance config file this host was launched with.
+ * @property {number|null} [claimAt] When the provisional claim was written (epoch ms).
+ * @property {number|null} [claimPid] PID of the service process that wrote the claim.
+ * @property {{pid:number,startToken:string|null}|null} [claimIdentity] Launch-time identity of the claiming service process.
+ * @property {{pid:number,startToken:string|null}|null} [runnerIdentity] Stable identity of the runner process.
+ * @property {number|null} [runnerSpawnedAt] When the runner spawn was confirmed (null = not yet spawned).
+ * @property {{pid:number,startToken:string|null}|null} [childIdentity] Stable identity of the child Pi process.
+ * @property {number|null} [childSpawnedAt] When the child spawn was confirmed (null = not yet spawned).
+ * @property {number|null} [readyAt] Set only after endpoint bind + child creation; alive implies readyAt != null.
+ * @property {number|null} [stopRequestedAt] When a revoke was requested via the host record.
+ * @property {string|null} [revokeToken] Random token written by requestHostStop to fence duplicate revokes.
+ * @property {string|null} [stopReason] Human-readable reason recorded with the revoke.
+ */
+
+/**
+ * Durable per-run snapshot (`runs/<runId>/status.json`).
+ * @typedef {Object} RunStatus
+ * @property {number} version
+ * @property {string} runId
+ * @property {string} viewId
+ * @property {number|null} pid
+ * @property {number} startedAt
+ * @property {number|null} endedAt
+ * @property {number|null} exitCode
+ * @property {RunKind} kind
+ * @property {string} prompt
+ * @property {string|null} model
+ * @property {SemanticState} semanticState
+ * @property {ProcessState} processState
+ * @property {string} summary
+ * @property {number} lastActivityAt
+ * @property {{name:string, path:string|null}|null} currentTool
+ * @property {string} latestAssistantPreview
+ * @property {string|null} question
+ * @property {Array<{toolCallId:string, question:string}>} pendingQuestions
+ * @property {string|null} error
+ * @property {number|null} lastAgentActivityAt Timestamp of the latest assistant reply.
+ * @property {string|null} stopReason
+ * @property {boolean} stoppedByUser
+ * @property {number} turns
+ * @property {number} toolCount
+ * @property {number} [eventCount]
+ * @property {number|null} [lastEventAt]
+ * @property {number} [updatedAt] In-memory foreground rebuild freshness (issue #225); not persisted on run status files.
+ * @property {EvidenceUsage|null} [usage]
+ * @property {string|null} [stallReason]
+ * @property {ReviewSummary|null} [evidenceSummary]
+ * @property {number} [materializedRevision] Coordinator-stamped monotonic revision shared with the view's state.json (issue #91). Absent on legacy rows until first coordinator materialization.
+ * @property {AutoStateClassification|null} [autoState]
+ */
+
+/**
+ * Configuration handed to the detached runner (written to the run dir as `config.json`
+ * and passed by path on argv).
+ * @typedef {Object} RunConfig
+ * @property {string} root
+ * @property {string} viewId
+ * @property {string} runId
+ * @property {RunKind} kind
+ * @property {string} sessionFile
+ * @property {string} cwd
+ * @property {string} prompt
+ * @property {string} piCommand        Executable to launch the worker (e.g. "pi" or a node path).
+ * @property {string[]} piArgsPrefix   Args before our flags (e.g. [cliJsPath] when piCommand is node).
+ * @property {string|null} model
+ * @property {"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|null} thinkingLevel
+ * @property {string|null} tools
+ */
+
+/**
+ * Configuration handed to the detached PTY host runner (written as `host-config.json`).
+ * @typedef {Object} HostConfig
+ * @property {string} root
+ * @property {string} viewId
+ * @property {string} sessionFile
+ * @property {string} cwd
+ * @property {string|null} initialPrompt
+ * @property {string} piCommand
+ * @property {string[]} piArgsPrefix
+ * @property {string|null} model
+ * @property {"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|null} thinkingLevel
+ * @property {string|null} tools
+ * @property {Record<string,string>} env
+ * @property {number} cols
+ * @property {number} rows
+ * @property {number|null} screenLogMaxBytes per-view screen.log write cap; null = runner default
+ * @property {string|null} [instanceId] Owner/fencing token for this host launch (issue #70).
+ * @property {string|null} [configPath] Per-instance config file path; each launch owns its own so concurrent launches never share a config.
+ * @property {string|null} [socketPath] Per-instance control endpoint the spawned runner must bind.
+ */
+
+/**
+ * Configuration handed to the detached title runner (written as `title-config.json`).
+ * @typedef {Object} TitleConfig
+ * @property {string} root
+ * @property {string} viewId
+ * @property {string} cwd
+ * @property {string} prompt
+ * @property {string} fallbackName
+ * @property {string} piCommand
+ * @property {string[]} piArgsPrefix
+ * @property {string|null} model
+ */
+
+/**
+ * Configuration handed to the detached auto-state runner.
+ * @typedef {Object} AutoStateConfig
+ * @property {string} root
+ * @property {string} viewId
+ * @property {string|null} runId
+ * @property {string} cwd
+ * @property {string} piCommand
+ * @property {string[]} piArgsPrefix
+ */
+
+/**
+ * @typedef {Object} DiagnosticEvent
+ * @property {number} version
+ * @property {number} at
+ * @property {string} viewId
+ * @property {string|null} runId
+ * @property {DiagnosticSource|string} source
+ * @property {DiagnosticLevel} level
+ * @property {string} code
+ * @property {string} message
+ * @property {Record<string,any>} details
+ */
+
+/**
+ * @typedef {Object} DiagnosticSummary
+ * @property {number} count
+ * @property {number} warningCount
+ * @property {number} errorCount
+ * @property {number|null} lastAt
+ * @property {DiagnosticLevel|null} lastLevel
+ * @property {string|null} lastCode
+ * @property {string|null} lastMessage
+ * @property {boolean} stalled
+ * @property {string|null} stallReason
+ */
+
+/**
+ * @typedef {Object} EvidenceUsage
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} totalTokens
+ */
+
+/**
+ * @typedef {Object} EvidenceCommand
+ * @property {string} id
+ * @property {number} at
+ * @property {string} command
+ * @property {EvidenceCommandKind} kind
+ * @property {EvidenceCommandStatus} status
+ * @property {number|null} exitCode
+ * @property {number|null} durationMs
+ * @property {string} outputPreview
+ */
+
+/**
+ * @typedef {Object} EvidenceFileChange
+ * @property {string} path
+ * @property {EvidenceFileAction} action
+ * @property {string|null} toolName
+ * @property {number} firstSeenAt
+ * @property {number} lastSeenAt
+ * @property {number} count
+ */
+
+/** @typedef {{ at:number, source:string, message:string, toolName:string|null }} EvidenceError */
+/** @typedef {{ at:number, text:string }} EvidenceAssistantClaim */
+
+/**
+ * @typedef {Object} EvidenceSnapshot
+ * @property {number} version
+ * @property {string} viewId
+ * @property {string|null} runId
+ * @property {number} updatedAt
+ * @property {EvidenceOutcome|string} outcome
+ * @property {boolean} ready
+ * @property {string} summary
+ * @property {EvidenceCommand[]} commands
+ * @property {EvidenceFileChange[]} fileChanges
+ * @property {EvidenceError[]} errors
+ * @property {EvidenceAssistantClaim[]} assistantEvidence
+ * @property {EvidenceUsage|null} usage
+ * @property {number} [eventCount]
+ * @property {string} [source]
+ */
+
+/**
+ * @typedef {Object} ReviewSummary
+ * @property {boolean} ready
+ * @property {EvidenceOutcome|string} outcome
+ * @property {number} fileChangeCount
+ * @property {number} commandCount
+ * @property {number} failedCommandCount
+ * @property {number} errorCount
+ * @property {string} latestAssistantEvidence
+ * @property {number|null} updatedAt
+ */
+
+/**
+ * @typedef {Object} FollowUpItem
+ * @property {string} id
+ * @property {number} seq
+ * @property {string} viewId
+ * @property {FollowUpKind} kind
+ * @property {string} text
+ * @property {number} createdAt
+ * @property {number} updatedAt
+ * @property {FollowUpStatus} status
+ * @property {string} source
+ * @property {"auto"|"now"|"queue"} delivery
+ * @property {string|null} runId
+ * @property {number|null} claimedAt
+ * @property {number|null} completedAt
+ * @property {number} attempts
+ * @property {string|null} error
+ */
+
+/** @typedef {{ version:number, viewId:string, nextSeq:number, updatedAt:number, items:FollowUpItem[] }} FollowUpQueue */
+/** @typedef {{ queuedCount:number, claimedCount:number, lastQueuedAt:number|null, lastQueuedPreview:string|null }} FollowUpSummary */
+
+/**
+ * @typedef {Object} SteeringState
+ * @property {number} version
+ * @property {string} viewId
+ * @property {SteeringModeState} status
+ * @property {number} updatedAt
+ * @property {string} planText
+ * @property {string|null} planRunId
+ * @property {number|null} approvedAt
+ * @property {string|null} changeRequest
+ * @property {string|null} executionRunId
+ * @property {Array<{at:number, from:string, to:string, action:string, runId:string|null, note:string|null}>} history
+ */
+
+/** @typedef {{ status:SteeringModeState, awaitingApproval:boolean, planPreview:string|null, updatedAt:number|null, question:string|null }} SteeringSummary */
+
+/**
+ * Compact issue/PR reference summary for a view (`github.json`).
+ * @typedef {Object} CodeRefsSummary
+ * @property {string|null} provider Resolved provider name (e.g. "github"); always non-null after a successful extraction (falls back to "generic"), null only before any extraction has run.
+ * @property {string} issuePrefix Issue-number prefix resolved from the matched provider at write time (default "#").
+ * @property {string} prPrefix PR/MR-number prefix resolved from the matched provider at write time (default "▸#"; "!" for gitlab).
+ * @property {import("./code-refs.mjs").Ref|null} issue
+ * @property {import("./code-refs.mjs").Ref|null} pr
+ * @property {import("./code-refs.mjs").Ref[]} allRefs Distinct refs for the peek view (max 10).
+ */
+
+/** Roster index (`roster.json`). @typedef {Object} Roster @property {number} version @property {string[]} views */
+
+/**
+ * Persisted launch dialog defaults (`launch-prefs.json`).
+ * @typedef {Object} LaunchPrefs
+ * @property {number} version
+ * @property {string|null} cwd
+ * @property {string|null} model
+ * @property {"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|null} thinkingLevel
+ * @property {number|null} screenLogRetentionDays days before an ended view's screen.log is GC'd; 0 disables GC
+ * @property {number|null} screenLogMaxSize per-view screen.log write cap in bytes; null = built-in default
+ */
+
+export {};

package/packages/board/src/core/warm-host-sweeper.mjs

@@ -0,0 +1,168 @@
+/**
+ * Warm-host sweep reclaim (issue #75).
+ *
+ * Idle PTY hosts must not live forever: after detach the runner is a detached
+ * orphan that nothing else will reap (Windows has no parent-death cascade, and
+ * the dashboard host may exit without a cleanup hook). The design intent
+ * (AGENT_BOARD_WARM_HOST_TTL_MS / MAX_WARM_HOSTS) already exists in
+ * service.mjs pruneWarmHosts but only fires lazily on attach/prewarm/dispatch.
+ * This module extracts the pure eviction decision plus a periodic sweeper so
+ * the TTL actually runs.
+ */
+
+/** @param {import("./store.mjs").Row} row */
+export function hasPendingQuestions(row) {
+	return Array.isArray(row.state?.pendingQuestions) && row.state.pendingQuestions.length > 0;
+}
+
+/**
+ * Busy = an agent run is active (queued/working) or the session is waiting on
+ * user questions. Idle/completed/failed/stopped are never busy.
+ * @param {import("./store.mjs").Row} row
+ */
+export function isAgentBusy(row) {
+	const st = row.state?.semanticState;
+	return Boolean(row.alive && (st === "queued" || st === "working" || hasPendingQuestions(row)));
+}
+
+/**
+ * Whether queued follow-ups may auto-drain for this row (issue #145).
+ * Deliberately an allow-list: a manual verdict state outside {idle, completed}
+ * (today: holding) must never be woken by the follow-up queue — only the user
+ * resumes it. Pure row predicate; co-located with isAgentBusy, which it
+ * composes, so both share this unit-test home.
+ * @param {import("./store.mjs").Row} row
+ */
+export function canAutoDrain(row) {
+	const st = row.state?.semanticState;
+	return !isAgentBusy(row) && (st === "idle" || st === "completed");
+}
+
+/**
+ * Pure eviction decision for warm PTY hosts. No IO, no env: every threshold is
+ * passed in so the logic is directly unit-testable.
+ *
+ * idle = host alive && !busy && no attached clients && not keepViewId.
+ * graceMs exempts freshly started hosts (attach handoff race: ensureHost has
+ * started a host but the client has not connected yet).
+ * isProtected is injected by the caller (this pure function never reads disk):
+ * a host running a background workflow is exempt from both eviction branches.
+ * TTL eviction runs first; survivors over maxWarm are evicted oldest-first by
+ * idleSince = max(state.lastActivityAt, host.startedAt) || meta.updatedAt (host-level
+ * idle counts from host start, so a stale lastActivityAt from a previous host
+ * incarnation never makes a fresh host look idle longer than it has been up).
+ *
+ * @param {Array<import("./store.mjs").Row>} rows
+ * @param {{ now: number, maxWarm: number, ttlMs: number, graceMs?: number, keepViewId?: string|null, isProtected?: ((row: import("./store.mjs").Row) => boolean)|null }} o
+ * @returns {{ ttlEvicted: string[], excessEvicted: string[] }} viewIds, ttl group first
+ */
+export function selectIdleHostsToEvict(rows, { now, maxWarm, ttlMs, graceMs = 0, keepViewId = null, isProtected = null }) {
+	// Both-zero = eviction disabled entirely. Callers (service.pruneWarmHosts)
+	// may additionally early-return for the same reason.
+	if (maxWarm === 0 && ttlMs === 0) return { ttlEvicted: [], excessEvicted: [] };
+	const idle = [];
+	for (const row of rows) {
+		if (keepViewId != null && row.meta.id === keepViewId) continue;
+		if (!row.hostAlive) continue;
+		if (isAgentBusy(row)) continue;
+		// Background-run protection (issue #230): a host executing a background
+		// workflow still counts as busy even though the assistant turn ended.
+		if (isProtected && isProtected(row)) continue;
+		if ((row.host?.attachedClients ?? 0) !== 0) continue;
+		const startedAt = row.host?.startedAt;
+		if (graceMs > 0 && startedAt != null && now - startedAt < graceMs) continue;
+		// Host-level idle counts from host start: a stale lastActivityAt from a
+		// previous host incarnation must not make a freshly prewarmed host look
+		// idle for longer than it has actually been up (issue #75 review #1).
+		const idleSince = Math.max(row.state?.lastActivityAt ?? 0, startedAt ?? 0) || row.meta.updatedAt;
+		idle.push({ id: row.meta.id, idleSince });
+	}
+	const ttlEvicted = [];
+	const survivors = [];
+	for (const it of idle) {
+		// Keep the historical semantics: ttlMs === 0 disables the ttl branch
+		// (only the maxWarm cap applies); both zero disables eviction entirely.
+		if (ttlMs > 0 && now - it.idleSince > ttlMs) ttlEvicted.push(it.id);
+		else survivors.push(it);
+	}
+	survivors.sort((a, b) => a.idleSince - b.idleSince);
+	const excess = Math.max(0, survivors.length - maxWarm);
+	return { ttlEvicted, excessEvicted: survivors.slice(0, excess).map((it) => it.id) };
+}
+
+/**
+ * Periodic sweeper for warm hosts. The interval timer is unref'd so it never
+ * holds the host pi's event loop open on exit. intervalMs <= 0 disables the
+ * periodic part; sweepNow() always works.
+ *
+ * stop() only stops the periodic timer: sweepNow() stays available afterwards
+ * (the lifecycle wiring calls sweepNow() again on shutdown/dispose). start()
+ * is idempotent and may restart the timer after a stop.
+ * @param {{ sweep: () => void, intervalMs: number }} o
+ */
+export function createWarmHostSweeper({ sweep, intervalMs }) {
+	let timer = null;
+	return {
+		active: true,
+		start() {
+			if (timer !== null) return;
+			if (intervalMs > 0) {
+				timer = setInterval(() => {
+					try { sweep(); } catch { /* best-effort */ }
+				}, intervalMs);
+				if (typeof timer.unref === "function") timer.unref();
+			}
+		},
+		sweepNow() {
+			try { sweep(); } catch { /* best-effort */ }
+		},
+		stop() {
+			if (timer !== null) {
+				clearInterval(timer);
+				timer = null;
+			}
+		},
+	};
+}
+
+/**
+ * Wire the sweeper to a host pi extension lifetime: sweep once on attach
+ * (reclaims hosts leaked by a previous host that died without cleanup), run
+ * periodically, and sweep again on session_shutdown (host pi exiting or the
+ * extension instance being reloaded for a session switch).
+ *
+ * Child pi processes (AGENT_BOARD_CHILD=1 / AGENT_VIEW_CHILD=1) must never
+ * sweep: they share the same board root and would terminate their own runner
+ * (suicide chain). They get a strict no-op.
+ *
+ * @param {{ on?: (event: any, fn: () => void) => any }} pi — any, not a narrower
+ *   string-keyed signature: pi's ExtensionAPI.on is a union of literal event-name
+ *   overloads and would otherwise fail structural assignment from TypeScript
+ *   callers (contravariant parameter check).
+ * @param {{ isHostedChild: boolean, sweep: () => void, intervalMs: number }} o
+ */
+export function attachWarmHostSweeper(pi, { isHostedChild, sweep, intervalMs }) {
+	// Child pi processes and board-spawned non-host workers must never sweep:
+	// children would terminate their own runner (suicide chain); workers
+	// (job/state runners set AGENT_BOARD_NO_SWEEP=1) would churn the shared root.
+	if (isHostedChild || process.env.AGENT_BOARD_NO_SWEEP === "1") {
+		return { active: false, dispose() {} };
+	}
+	const sweeper = createWarmHostSweeper({ sweep, intervalMs });
+	let shutdown = false;
+	const onShutdown = () => {
+		if (shutdown) return;
+		shutdown = true;
+		sweeper.sweepNow();
+		sweeper.stop();
+	};
+	pi.on?.("session_shutdown", onShutdown);
+	sweeper.start();
+	sweeper.sweepNow(); // 回收上一个宿主（可能非正常退出）遗留的 warm hosts
+	return {
+		active: true,
+		dispose() {
+			onShutdown();
+		},
+	};
+}

package/packages/board/src/core/worktree.mjs

@@ -0,0 +1,65 @@
+/**
+ * Git worktree isolation for same-repo parallel writer sessions (plan §11.2).
+ * Each managed view gets its own worktree + branch so concurrent writers never clobber.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * @param {string} repoRoot
+ * @param {string[]} args
+ * @returns {{ ok: boolean, stdout: string, error: string|null }}
+ */
+function git(repoRoot, args) {
+	try {
+		const stdout = execFileSync("git", ["-C", repoRoot, ...args], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+		return { ok: true, stdout: stdout.trim(), error: null };
+	} catch (err) {
+		const e = /** @type {any} */ (err);
+		const error = (e?.stderr?.toString?.() || e?.message || "git error").trim();
+		return { ok: false, stdout: "", error };
+	}
+}
+
+/**
+ * Create a worktree at `worktreePath` on a fresh branch `branch`, based on HEAD.
+ * Idempotent-ish: if the path already exists we assume it's already a worktree.
+ * @param {string} repoRoot
+ * @param {string} worktreePath
+ * @param {string} branch
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function addWorktree(repoRoot, worktreePath, branch) {
+	if (existsSync(worktreePath)) return { ok: true, error: null };
+	// Try with a new branch first; fall back to attaching if the branch already exists.
+	let res = git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
+	if (!res.ok && /already exists/i.test(res.error ?? "")) {
+		res = git(repoRoot, ["worktree", "add", worktreePath, branch]);
+	}
+	return { ok: res.ok, error: res.error };
+}
+
+/**
+ * Remove a worktree (forced) and prune. Best-effort.
+ * @param {string} repoRoot
+ * @param {string} worktreePath
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function removeWorktree(repoRoot, worktreePath) {
+	const res = git(repoRoot, ["worktree", "remove", "--force", worktreePath]);
+	git(repoRoot, ["worktree", "prune"]);
+	return { ok: res.ok, error: res.error };
+}
+
+/**
+ * A short, filesystem/branch-safe identifier for a view's worktree branch.
+ * @param {string} viewId
+ * @returns {string}
+ */
+export function worktreeBranch(viewId) {
+	return `agent-board/${viewId}`;
+}