pi-squad 0.17.0 → 0.17.2

package/README.md

@@ -90,6 +90,14 @@ squad_modify({ action: "resume_task", squadId: "<exact-squad-id>", taskId: "<exa
 
 Repeated reconciliation and restart do not create notification storms. A delivered stall remains visible until explicit resumption changes the state; a different suspended/blocked set is a new actionable episode.
 
+### Persistent Master Switch
+
+`/squad disable` persists a global master switch in `~/.pi/squad/settings.json`. It first saves the disabled state, then stops schedulers, durably suspends in-progress tasks, kills child processes, clears focus, and hides the widget. On later Pi restarts, disabled mode does not reconstruct schedulers, recover mail, resume sessions, normalize tasks, or select a squad.
+
+While disabled, all five squad tools and every `/squad` operation fail closed with `/squad enable` guidance; only exact `/squad enable` and the idempotent exact `/squad disable` control commands run. Tool schemas remain registered. Mandatory pending/failed review gates and suspended-stall reminders remain injected because they are durable safety obligations, but they do not authorize squad work while disabled.
+
+`/squad enable` persists the enabled state and restores widget availability without selecting a squad or resuming anything. Suspended work remains suspended until an explicit exact-task resume or `/squad resume <squad-id>`.
+
 ### QA Rework Loop
 
 When a QA agent outputs `## Verdict: FAIL`, the scheduler automatically:
@@ -217,7 +225,7 @@ Full overlay with task list, live activity preview, and scrollable message view.
 | `/squad cancel` | Cancel the visibly focused squad; the notification names it and the focused widget/status clear |
 | `/squad clear` | Dismiss widget |
 | `/squad cleanup` | Delete squad data |
-| `/squad enable/disable` | Enable/disable the extension |
+| `/squad enable/disable` | Persistently enable/disable all squad execution; enabling never auto-resumes work |
 
 ## Tools (LLM-callable)
 
@@ -225,6 +233,7 @@ Full overlay with task list, live activity preview, and scrollable message view.
 |---|---|
 | `squad` | Start a squad with goal + optional tasks/config |
 | `squad_status` | Check progress, costs, task states |
+| `squad_review` | Record the main orchestrator's independent acceptance review |
 | `squad_message` | Durably message an exact task; completed tasks reopen on their original session |
 | `squad_modify` | Add/cancel/complete/pause/resume tasks or squads, or replace a task's dependencies with `set_dependencies`; exact `squadId` is required for destructive whole-squad `cancel` and recommended for all task actions |
 
@@ -331,7 +340,7 @@ Agents must complete at least one LLM turn and produce either a tool call or a s
 
 - Every task owns one durable Pi session. New tasks create it under their task directory; stale, suspended, failed, or explicitly reopened tasks resume that same session rather than starting over. A pre-prompt retry may refresh Pi's provisional session ID only while the bound file is the same and its JSONL has not materialized; afterward both file and ID are immutable.
 - Legacy tasks without a session binding migrate on first reopen by creating a task-owned session and seeding its first prompt with the complete persisted multiline message history and prior task output—without truncation.
-- In-progress tasks are **suspended** on orderly shutdown; ordinary orphaned work is paused for explicit resume. If a scheduler itself is reconstructed, stale `in_progress` state is resumed by reconciliation. Independently, extension startup always reconstructs any project squad with pending mailbox entries—including `review` or already accepted `done` squads—and resumes delivery without another user action.
+- In-progress tasks are **suspended** on orderly shutdown; ordinary orphaned work is paused for explicit resume. When the persistent master switch is enabled, a reconstructed scheduler can resume stale `in_progress` state through reconciliation, and startup reconstructs project squads with pending mailbox entries—including `review` or already accepted `done` squads—to resume delivery. Disabled startup performs none of this recovery.
 - A durable message to a completed task clears its prior completion/review state, reopens the squad, keeps the task `in_progress` while its agent is live, and requires a fresh orchestrator review after the final `agent_settled`. Every transitive descendant is re-blocked and reruns in dependency order, so results derived from the reopened dependency cannot remain falsely complete.
 - Failure is never terminal: `resume` recovers failed squads (failed tasks reset to pending), `complete_task` marks recovered work done and schedules dependents, and a 60s reconcile loop re-derives scheduling from persisted state so out-of-band store edits can't strand ready tasks.
 - Mail is acknowledged only after Pi accepts the correlated RPC command. Pending and acknowledged entries remain task-addressed on disk, survive process restart, and remain visible in history. Queue and acknowledgement read/modify/write operations are serialized across processes so concurrent mutations cannot overwrite messages or delivery state.
@@ -355,6 +364,7 @@ All state in `~/.pi/squad/`. No database, no daemon. Writes are atomic. JSONL re
 
 ```
 ~/.pi/squad/
+├── settings.json        — persistent master switch, defaults, and advisor settings
 ├── agents/              — agent definitions (user-editable)
 ├── debug.log            — error and debug logging
 └── {squad-id}/

package/docs/persistent-master-switch-contract.md

@@ -0,0 +1,148 @@
+# Persistent squad master-switch contract
+
+Status: implementation contract (not current implementation truth)
+
+## 1. State and persistence
+
+The master switch is global, not project- or session-local.
+
+```ts
+interface SquadSettings {
+  enabled: boolean;
+  // existing defaultModel, defaultThinking, and advisor fields remain unchanged
+}
+
+DEFAULT_SQUAD_SETTINGS.enabled = true;
+```
+
+- Persist the value at `~/.pi/squad/settings.json` through the existing atomic settings writer.
+- A missing settings file, a legacy file without `enabled`, or a non-boolean `enabled` uses the backward-compatible default `true`. Other settings keep their existing deep-merge behavior.
+- Every whole-settings write (including `/squad defaults` and `/squad advisor`) must preserve the effective `enabled` value.
+- The extension loads the effective setting before any `session_start` widget installation, focus restoration, orphan cleanup, attestation audit, scheduler construction/start, suspended-stall recovery, mailbox recovery, or squad notification.
+- Tools and the `/squad` command remain statically registered in both states. Registration is not permission to execute.
+- The conditional child-only `squad_spec_read` registration is not a main-session squad execution path; its existing file-spec guard remains unchanged. Disabling the parent kills its child processes.
+
+A failed settings write fails the control command. It must not update the in-memory master state or claim success.
+
+## 2. Disabled startup
+
+When the loaded value is `false`, `session_start` is read-only with respect to squad work:
+
+- do not create or start a `Scheduler`;
+- do not audit or rewrite file-spec/task/squad state;
+- do not normalize orphaned `in_progress` tasks;
+- do not recover pending mail, resume sessions, acknowledge attention, or spawn children;
+- do not select/focus a squad, install/show squad widget content, open a panel, or register an operational Ctrl+Q path;
+- do not emit ordinary paused/recovery/completion/failure notifications.
+
+The only lifecycle exception is the durable safety injection in section 7. Reading persisted review/attention records for that injection is allowed; reconstructing or mutating work is not.
+
+An enabled startup retains existing recovery behavior and contracts. In particular, explicitly `suspended` tasks still never resume merely because Pi restarted.
+
+## 3. Public tool gate
+
+The enabled check is the first operation in every main-session tool `execute` handler, before target inference, store lookup, focus changes, scheduler construction, mailbox writes, review writes, or other mutations. While disabled, every tool returns a non-throwing result with clear guidance such as:
+
+```text
+pi-squad is disabled. Run /squad enable, then retry this operation; no squad work was changed.
+```
+
+All five public tools registered in `src/index.ts` are covered:
+
+| Tool | Disabled behavior |
+|---|---|
+| `squad` | No planning, publication, scheduler, task, or child creation. |
+| `squad_status` | No latest/active lookup or context refresh; fail closed rather than offering a read-only bypass. |
+| `squad_review` | No attestation scheduler/audit and no review mutation. The durable review gate remains pending/failed and injected. |
+| `squad_message` | No mailbox write, scheduler reconstruction, task reopening, or delivery. |
+| `squad_modify` | Every action fails closed, including add/set-dependencies/cancel/pause/resume/complete and whole-squad actions. |
+
+Static schemas/descriptions remain available to the model, but a call cannot execute until enabled.
+
+## 4. Slash-command and UI gate
+
+The `/squad` handler checks the master state before defaulting, resolving a direct squad ID, reading targets, or opening interactive UI.
+
+While disabled:
+
+- exact `/squad enable` is allowed;
+- repeated `/squad disable` is an idempotent control-plane no-op that reports the extension is already disabled and points to `/squad enable`; it never reconstructs work;
+- every other form returns one clear disabled notification and performs no squad-work or settings mutation.
+
+This covers every registered branch and fallback in `src/index.ts`:
+
+| Form | Disabled result |
+|---|---|
+| `/squad`, `/squad select`, `/squad list`, `/squad all`, `/squad <squad-id>` | No selection, focus, or store-driven UI. |
+| `/squad resume [id]` | No scheduler construction or task/squad transition. |
+| `/squad msg ...` | No mailbox or task mutation. |
+| `/squad widget`, `/squad panel`, `/squad clear` | No view activation or panel/widget bypass. |
+| `/squad cancel`, `/squad cleanup [all]` | No stopping/deleting/mutating persisted squads. |
+| `/squad agents`, `/squad defaults`, `/squad advisor` | No agent/settings editor mutation while the master switch is off. |
+
+Ctrl+Q and all already-created panel callbacks obey the same gate: while disabled they may consume the input and show enable guidance, but may not resolve/focus a squad, construct/start a scheduler, send mail, pause/resume/cancel tasks, or mutate work. If an overlay is open during disable, close it when supported; regardless, its callbacks must fail closed.
+
+## 5. `/squad disable` transition
+
+From enabled state, ordering is mandatory:
+
+1. Load current settings, set `enabled: false`, and atomically persist them. If this fails, abort without claiming or entering disabled mode.
+2. Set the in-memory master state to false immediately after persistence, so concurrent public paths fail closed during shutdown.
+3. Stop every registered scheduler. Existing `Scheduler.stop()` ordering remains authoritative: stop monitor/reconcile, durably change each `in_progress` task to `suspended`, then kill all child processes. Await every stop/kill before reporting success.
+4. Clear the scheduler registry and active focus. Do not reconstruct an absent scheduler merely to disable it.
+5. Force `widgetState.enabled = false`, clear its squad target/status, request a render clear (or dispose the widget), and prevent late scheduler events from showing it again.
+6. Leave all pending/failed review evidence, review history, mailbox data, sessions, cancellation state, file-spec evidence, and suspended-stall attention intact.
+7. Notify truthfully that pi-squad is disabled and `/squad enable` is required.
+
+The operation is idempotent. Repeating it while already disabled does not rewrite tasks, resume work, create schedulers, or duplicate children; it reports the already-disabled state. A task already suspended remains suspended.
+
+## 6. `/squad enable` transition and no-auto-resume rule
+
+Ordering is symmetric at the persistence boundary:
+
+1. Load current settings, set `enabled: true`, and atomically persist them. On failure, remain disabled.
+2. Set the in-memory master state to true.
+3. Restore widget *availability* (`widgetState.enabled = true` and install/request its controls when UI exists), but keep focus cleared unless the user explicitly selects a squad. An empty widget is valid.
+4. Do not construct/start a scheduler, audit work, recover mail, reopen a task, resume a child session, select a squad, clear an attention record, or change any squad/task status.
+5. Notify: pi-squad is enabled; no suspended work was resumed; `/squad select` and an explicit `/squad resume <id>` or exact `squad_modify resume_task` may be required.
+
+Repeated enable is idempotent: it converges persisted/in-memory enabled state and widget availability without spawning, selecting, resuming, or duplicating anything.
+
+**Explicit consent is required after disable.** Work suspended by disable remains suspended across `/squad enable` and across disabled restarts. Selection is view-only. Only a later explicit resume operation may revive it, using the existing exact-target, task-session, mailbox, descendant-invalidation, and failed-review-history contracts.
+
+## 7. Authoritative safety reminders while disabled
+
+Master disable suppresses ordinary squad hints/status prompts and operational event notifications, but it must never hide or weaken these persisted safety obligations:
+
+1. Every project squad in `review` keeps its complete mandatory orchestrator review gate injected by `before_agent_start`, across focus changes and while disabled. Candidate work remains untrusted and cannot become accepted. Because `squad_review` is fail-closed while disabled, the injected guidance must state that `/squad enable` is required before recording the independent review.
+2. Every active persisted `suspendedStallAttention` keeps its complete exact squad ID, suspended IDs, blocked IDs, and “No task was resumed automatically” reminder injected project-wide while disabled. Guidance must state: enable first, then explicitly resume only intended exact tasks.
+
+These are read-only, durable prompt injections, not permission to reconstruct a scheduler, acknowledge an outbox record, auto-resume work, or call a blocked tool. Review evidence and suspended-attention data remain authoritative and untruncated.
+
+## 8. Widget and event behavior
+
+The master switch outranks the separate session-local `/squad widget` preference.
+
+- Disabled means no widget body and no squad status-line content, even if a prior widget toggle was on or a late scheduler event arrives.
+- Disable clears focus and hides immediately after children are quiesced; enable restores the widget mechanism but does not infer a target.
+- Ordinary `before_agent_start` squad hints/active status are absent while disabled; only section 7 safety text remains.
+- Late scheduler callbacks after disable must not emit ordinary review/failure/reply/escalation UI or re-enable/focus the widget. Their durable state must still obey existing cancellation, suspension, and review guards.
+
+## 9. Required regression matrix
+
+Implementation tests must prove persisted state as well as returned text:
+
+1. Missing/legacy settings default enabled; `false` and `true` survive extension/session restart; other settings survive both writes.
+2. Disabled startup creates zero schedulers/children and performs zero orphan, attestation, mailbox, focus, widget, or task/squad mutation.
+3. Each of the five registered public tools fails before lookup/reconstruction/mutation and includes `/squad enable` guidance.
+4. Every slash branch/fallback listed in section 4, default `/squad`, direct-ID activation, Ctrl+Q, and panel actions have no disabled bypass.
+5. Disable persists before stop, suspends live tasks durably, kills all children, clears scheduler/focus, and hides widget; a persistence failure leaves enabled runtime unchanged.
+6. Enable restores widget availability and clear guidance but does not select, reconstruct, recover, or resume work.
+7. Repeated enable/disable causes no duplicate scheduler/child, task rewrite, or auto-resume.
+8. Disabled restart and later enable leave suspended tasks suspended; only explicit exact resume changes them.
+9. Pending/failed review and delivered/pending suspended-attention reminders remain complete and injected while disabled, with enable-first guidance; no review/attention record is mutated.
+10. Existing cancellation, mandatory review, file-spec/attestation, mailbox/session, no-truncation, and suspended-stall suites remain green.
+
+## 10. Registration cross-check
+
+`src/index.ts` currently exposes exactly five main-session tools (`squad`, `squad_status`, `squad_review`, `squad_message`, `squad_modify`) and one `/squad` command whose branches are `list`, `all`, `select`, `resume`, `widget`, `panel`, `msg`, `cancel`, `clear`, `cleanup`, `enable`, `disable`, `defaults`, `advisor`, `agents`, plus default selection and direct-ID fallback. Sections 3 and 4 cover every registration and branch. The session-start Ctrl+Q panel path and panel callbacks are covered separately because they are public execution surfaces even though they are not slash commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -20,9 +20,9 @@ import { Scheduler, formatSuspendedStallAttention, type SchedulerEvent, type Sch
 import { runPlanner } from "./planner.js";
 import { validatePlan, PLAN_STRUCTURE_RULES } from "./plan-rules.js";
 import { ADVISOR_SYSTEM_PROMPT, buildAdvisorConsultText, type AdvisorConsultInput } from "./advisor.js";
-import { completeSimple, type Message, type TextContent } from "@earendil-works/pi-ai";
+import { completeSimple, type Message, type TextContent } from "@earendil-works/pi-ai/compat";
 import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
-import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js";
+import { setupSquadWidget, type SquadWidgetControls, type SquadWidgetState } from "./panel/squad-widget.js";
 import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildCompletionSummary, buildFailureSummary } from "./report.js";
@@ -41,19 +41,34 @@ interface InlineSquadStart {
 	config?: { maxConcurrency?: number; autoUnblock?: boolean; maxRetries?: number };
 }
 
-/** Master switch — when false, all squad tools, hooks, and widget are disabled */
+/** Master switch — loaded from ~/.pi/squad/settings.json before lifecycle work. */
 let squadEnabled = true;
+const DISABLED_GUIDANCE = "pi-squad is disabled. Run /squad enable, then retry this operation; no squad work was changed.";
+const disabledToolResult = () => ({
+	content: [{ type: "text" as const, text: DISABLED_GUIDANCE }],
+	details: undefined,
+});
 /** Registry of all running schedulers — supports multiple concurrent squads */
 const schedulers = new Map<string, Scheduler>();
 /** The currently viewed/focused squad (for widget, panel, status) */
 let activeSquadId: string | null = null;
 /** Whether an overlay panel is currently open (prevents double-open) */
 let overlayOpen = false;
+/** Close an already-open overlay when the master switch is disabled. */
+let closeOverlay: (() => void) | null = null;
 /** Stored ExtensionContext for widget updates from background scheduler events */
 let uiCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = null;
 /** Component-based widget state + controls */
 const widgetState: SquadWidgetState = { squadId: null, enabled: true };
-let widgetControls: { requestUpdate: () => void; dispose: () => void } | null = null;
+let widgetControls: SquadWidgetControls | null = null;
+
+/** Keep main-session focus, compact widget, and detail panel targeting identical. */
+function focusSquad(squadId: string | null): void {
+	activeSquadId = squadId;
+	widgetState.squadId = squadId;
+	if (squadId && squadEnabled) widgetState.enabled = true;
+	widgetControls?.refreshNow();
+}
 
 /** Format completion against active work while retaining cancelled history. */
 function formatTaskProgress(tasks: Task[]): string {
@@ -197,11 +212,10 @@ function getActiveScheduler(): Scheduler | null {
 
 /** Restore the single focus/widget invariant after destructive exact cancellation. */
 function repairFocusAfterCancellation(cancelledId: string): void {
-	if (activeSquadId === cancelledId || (activeSquadId !== null && !store.loadSquad(activeSquadId))) {
-		activeSquadId = null;
-	}
-	widgetState.squadId = activeSquadId;
-	widgetControls?.requestUpdate();
+	const nextFocus = activeSquadId === cancelledId || (activeSquadId !== null && !store.loadSquad(activeSquadId))
+		? null
+		: activeSquadId;
+	focusSquad(nextFocus);
 }
 
 function activeSuspendedAttentionForProject(cwd: string): Array<{ squadId: string; attention: SuspendedStallAttention }> {
@@ -218,10 +232,7 @@ function ensureScheduler(pi: ExtensionAPI, squadId: string, skillPaths: string[]
 		schedulers.set(squadId, scheduler);
 		wireSchedulerEvents(pi, scheduler, squadId);
 	}
-	activeSquadId = squadId;
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	focusSquad(squadId);
 	return scheduler;
 }
 
@@ -251,6 +262,11 @@ export default function (pi: ExtensionAPI) {
 	// File-spec children load only the non-recursive reader and fail-closed guard.
 	if (process.env.PI_SQUAD_CHILD === "1") { registerChildSpecReader(pi); return; }
 
+	// Load the global master switch before any session lifecycle work can run.
+	squadEnabled = store.loadSquadSettings().enabled;
+	widgetState.enabled = squadEnabled;
+	if (!squadEnabled) focusSquad(null);
+
 	// Wire main-session thinking lookup (needs `pi`, guarded against stale API)
 	getMainSessionThinking = () => {
 		try {
@@ -286,6 +302,33 @@ export default function (pi: ExtensionAPI) {
 		return true;
 	};
 
+	/** Register a dynamically gated Ctrl+Q path; disabled mode can only show guidance. */
+	const registerTerminalPanelToggle = (ctx: ExtensionContext): void => {
+		if (!ctx.hasUI) return;
+		ctx.ui.onTerminalInput((data) => {
+			if (data !== "\x11") return undefined;
+			if (!squadEnabled) {
+				ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+				return { consume: true };
+			}
+			// If overlay is already open, let the panel's own handler deal with it.
+			if (overlayOpen) return undefined;
+			if (!activeSquadId) {
+				const latest = store.findLatestSquad(ctx.cwd)
+					|| store.listSquads().map((id) => store.loadSquad(id)).filter((s): s is Squad => s !== null).sort((a, b) => b.created.localeCompare(a.created))[0];
+				if (latest) activateSquadView(latest.id, ctx);
+				else {
+					ctx.ui.notify("No squads found. Use /squad or the squad tool.", "info");
+					return { consume: true };
+				}
+			}
+			if (activeSquadId) {
+				openPanel(pi, ctx, schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths, schedulerSpawnContext), activeSquadId);
+			}
+			return { consume: true };
+		});
+	};
+
 	// =========================================================================
 	// Context Injection — give main agent awareness of squad state
 	// =========================================================================
@@ -302,15 +345,17 @@ export default function (pi: ExtensionAPI) {
 		const durablePrompts = [...pendingReviewGates.map(({ gate }) => gate), ...suspendedAttention];
 		if (!squadEnabled) {
 			if (durablePrompts.length === 0) return;
-			return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
+			const enableFirst = durablePrompts.map((prompt) =>
+				`${prompt}\npi-squad is disabled. Run /squad enable first; then perform only the explicit review or exact-task resume described above.`,
+			);
+			return { systemPrompt: event.systemPrompt + "\n\n" + enableFirst.join("\n\n") };
 		}
 
 		// When a squad is active, inject its status
 		if (activeSquadId) {
 			const squad = store.loadSquad(activeSquadId);
 			if (!squad) {
-				activeSquadId = null;
-				widgetState.squadId = null;
+				focusSquad(null);
 				if (durablePrompts.length > 0) {
 					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
@@ -448,7 +493,7 @@ export default function (pi: ExtensionAPI) {
 		]),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			if (!squadEnabled) return { content: [{ type: "text" as const, text: "Squad is disabled. Use /squad enable to re-enable." }], details: undefined };
+			if (!squadEnabled) return disabledToolResult();
 			if (!uiCtx) uiCtx = ctx;
 
 			// Check if the user cancelled before we start
@@ -487,6 +532,7 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!squadEnabled) return disabledToolResult();
 			let id = params.squadId || activeSquadId;
 
 			// If no active squad, find the most recent one for this project
@@ -567,6 +613,7 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!squadEnabled) return disabledToolResult();
 			let id = params.squadId;
 			if (!id && activeSquadId && store.loadSquad(activeSquadId)?.status === "review") {
 				id = activeSquadId;
@@ -587,6 +634,7 @@ export default function (pi: ExtensionAPI) {
 			const attestationScheduler = schedulers.get(id) ?? new Scheduler(id, squadSkillPaths, schedulerSpawnContext);
 			if (!schedulers.has(id)) { schedulers.set(id, attestationScheduler); wireSchedulerEvents(pi, attestationScheduler, id); }
 			const invalidAttestations = await attestationScheduler.auditSpecAttestations();
+			if (!squadEnabled) return disabledToolResult();
 			if (invalidAttestations.length > 0) {
 				void attestationScheduler.start();
 				return { content: [{ type: "text" as const, text: `Review rejected: invalid canonical spec attestation for task(s): ${invalidAttestations.join(", ")}. Work was reopened.` }], details: undefined };
@@ -631,6 +679,7 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!squadEnabled) return disabledToolResult();
 			if (!activeSquadId) {
 				return { content: [{ type: "text" as const, text: "No active squad." }], details: undefined };
 			}
@@ -711,6 +760,7 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!squadEnabled) return disabledToolResult();
 			if (params.action === "cancel") {
 				if (!params.squadId?.trim()) {
 					return { content: [{ type: "text" as const, text: "cancel requires exact squadId; no squad was changed." }], details: undefined };
@@ -756,7 +806,7 @@ export default function (pi: ExtensionAPI) {
 			if (!activeScheduler) {
 				return { content: [{ type: "text" as const, text: `Squad '${squadId}' has no active scheduler. Use resume, add_task, or resume_task to reconstruct it.` }], details: undefined };
 			}
-			activeSquadId = squadId;
+			focusSquad(squadId);
 
 			switch (params.action) {
 				case "add_task": {
@@ -880,8 +930,24 @@ export default function (pi: ExtensionAPI) {
 	// =========================================================================
 
 	pi.on("session_start", async (_event, ctx) => {
+		// Re-read before touching focus, widgets, schedulers, or persisted work.
+		squadEnabled = store.loadSquadSettings().enabled;
 		uiCtx = ctx;
 
+		// A session replacement may not deliver shutdown first. Never carry a
+		// focused squad across projects, and never seed a new widget from stale state.
+		widgetControls?.dispose();
+		widgetControls = null;
+		registerTerminalPanelToggle(ctx);
+		if (!squadEnabled) {
+			widgetState.enabled = false;
+			focusSquad(null);
+			return;
+		}
+		widgetState.enabled = true;
+		const focused = activeSquadId ? store.loadSquad(activeSquadId) : null;
+		focusSquad(focused?.cwd === ctx.cwd ? activeSquadId : null);
+
 		// Install component-based widget
 		if (ctx.hasUI) {
 			widgetControls = setupSquadWidget(ctx, widgetState);
@@ -948,12 +1014,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			await scheduler.start();
 		}
-		if (pendingMailSquads.length > 0) {
-			activeSquadId = pendingMailSquads[0].id;
-			widgetState.squadId = activeSquadId;
-			widgetState.enabled = true;
-			widgetControls?.requestUpdate();
-		}
+		if (pendingMailSquads.length > 0) focusSquad(pendingMailSquads[0].id);
 
 		// Notify about paused squads only if they have real completed work
 		const paused = store.findActiveSquads()
@@ -979,10 +1040,7 @@ export default function (pi: ExtensionAPI) {
 			.filter((s) => s.cwd === ctx.cwd && s.status === "review");
 		if (pendingReviews.length > 0) {
 			const squad = pendingReviews.sort((a, b) => b.created.localeCompare(a.created))[0];
-			activeSquadId = squad.id;
-			widgetState.squadId = squad.id;
-			widgetState.enabled = true;
-			widgetControls?.requestUpdate();
+			focusSquad(squad.id);
 			const tasks = store.loadAllTasks(squad.id);
 			pi.sendMessage({
 				customType: "squad-review-required",
@@ -991,43 +1049,16 @@ export default function (pi: ExtensionAPI) {
 			});
 		}
 
-		// Register Ctrl+Q terminal input handler for panel toggle
-		if (ctx.hasUI) {
-			ctx.ui.onTerminalInput((data) => {
-				if (data === "\x11") {
-					// If overlay is already open, let the panel's own handler deal with it
-					if (overlayOpen) return undefined;
-
-					// Auto-pick a squad if none active
-					if (!activeSquadId) {
-						const latest = store.findLatestSquad(ctx.cwd)
-							|| store.listSquads().map((id) => store.loadSquad(id)).filter((s): s is Squad => s !== null).sort((a, b) => b.created.localeCompare(a.created))[0];
-						if (latest) {
-							activateSquadView(latest.id, ctx);
-						} else {
-							ctx.ui.notify("No squads found. Use /squad or the squad tool.", "info");
-							return { consume: true };
-						}
-					}
-
-					if (activeSquadId) {
-						openPanel(pi, ctx, schedulers.get(activeSquadId) || new Scheduler(activeSquadId, squadSkillPaths, schedulerSpawnContext), activeSquadId);
-					}
-					return { consume: true };
-				}
-				return undefined;
-			});
-		}
 	});
 
 	pi.on("session_shutdown", async () => {
+		focusSquad(null);
 		widgetControls?.dispose();
 		widgetControls = null;
 		for (const [id, sched] of schedulers) {
 			await sched.stop();
 		}
 		schedulers.clear();
-		activeSquadId = null;
 		uiCtx = null;
 	});
 
@@ -1058,7 +1089,12 @@ export default function (pi: ExtensionAPI) {
 			return subs.filter((s) => s.value.startsWith(prefix));
 		},
 		handler: async (args, ctx) => {
-			const parts = args.trim().split(/\s+/);
+			const requested = args.trim();
+			if (!squadEnabled && requested !== "enable" && requested !== "disable") {
+				ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+				return;
+			}
+			const parts = requested.split(/\s+/);
 			const sub = parts[0] || "select";
 
 			switch (sub) {
@@ -1252,8 +1288,7 @@ export default function (pi: ExtensionAPI) {
 
 				case "clear": {
 					if (activeSquadId) schedulers.delete(activeSquadId);
-					activeSquadId = null;
-					widgetState.squadId = null;
+					focusSquad(null);
 					widgetControls?.dispose();
 					ctx.ui.notify("Squad view cleared", "info");
 					return;
@@ -1274,9 +1309,7 @@ export default function (pi: ExtensionAPI) {
 							await sched.stop();
 						}
 						schedulers.clear();
-						activeSquadId = null;
-						widgetState.squadId = null;
-						widgetControls?.requestUpdate();
+						focusSquad(null);
 
 						let count = 0;
 						for (const id of allSquadIds) {
@@ -1312,9 +1345,7 @@ export default function (pi: ExtensionAPI) {
 							await sched.stop();
 						}
 						schedulers.clear();
-						activeSquadId = null;
-						widgetState.squadId = null;
-						widgetControls?.requestUpdate();
+						focusSquad(null);
 						let count = 0;
 						for (const id of allSquadIds) {
 							fs.rmSync(store.getSquadDir(id), { recursive: true, force: true });
@@ -1332,11 +1363,7 @@ export default function (pi: ExtensionAPI) {
 								await sched.stop();
 								schedulers.delete(squad.id);
 							}
-							if (activeSquadId === squad.id) {
-								activeSquadId = null;
-								widgetState.squadId = null;
-								widgetControls?.requestUpdate();
-							}
+							if (activeSquadId === squad.id) focusSquad(null);
 							fs.rmSync(store.getSquadDir(squad.id), { recursive: true, force: true });
 							ctx.ui.notify(`Deleted: ${squad.id}`, "info");
 						}
@@ -1345,24 +1372,48 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				case "enable": {
+					const wasEnabled = squadEnabled;
+					try {
+						const settings = store.loadSquadSettings();
+						settings.enabled = true;
+						store.saveSquadSettings(settings);
+					} catch (error) {
+						ctx.ui.notify(`Could not enable pi-squad: ${(error as Error).message}`, "error");
+						return;
+					}
 					squadEnabled = true;
+					widgetState.enabled = true;
+					if (!wasEnabled) widgetState.squadId = null;
+					if (!widgetControls && uiCtx?.hasUI) widgetControls = setupSquadWidget(uiCtx, widgetState);
 					widgetControls?.requestUpdate();
-					ctx.ui.notify("pi-squad enabled — tools, widget, and system prompt active", "info");
+					ctx.ui.notify("pi-squad enabled. No suspended work was resumed; use /squad select and an explicit /squad resume <id> or exact resume_task if needed.", "info");
 					return;
 				}
 
 				case "disable": {
-					squadEnabled = false;
-					// Stop all running schedulers
-					for (const [id, sched] of schedulers) {
-						await sched.stop();
+					if (!squadEnabled) {
+						ctx.ui.notify("pi-squad is already disabled. Run /squad enable to use squad operations.", "info");
+						return;
 					}
+					try {
+						const settings = store.loadSquadSettings();
+						settings.enabled = false;
+						store.saveSquadSettings(settings);
+					} catch (error) {
+						ctx.ui.notify(`Could not disable pi-squad: ${(error as Error).message}`, "error");
+						return;
+					}
+					// The persisted state is authoritative before shutdown begins.
+					squadEnabled = false;
+					closeOverlay?.();
+					for (const sched of schedulers.values()) await sched.stop();
 					schedulers.clear();
-					activeSquadId = null;
-					widgetState.squadId = null;
 					widgetState.enabled = false;
-					widgetControls?.requestUpdate();
-					ctx.ui.notify("pi-squad disabled — all tools, widget, and system prompt injection stopped", "info");
+					widgetState.squadId = null;
+					focusSquad(null);
+					widgetControls?.dispose();
+					widgetControls = null;
+					ctx.ui.notify("pi-squad disabled. Running work was durably suspended; run /squad enable before any squad operation.", "info");
 					return;
 				}
 
@@ -1627,19 +1678,19 @@ async function pickSquad(
  * Does NOT start a scheduler (view-only unless squad needs resuming).
  */
 function activateSquadView(squadId: string, ctx: import("@earendil-works/pi-coding-agent").ExtensionContext | import("@earendil-works/pi-coding-agent").ExtensionCommandContext): void {
+	if (!squadEnabled) {
+		ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+		return;
+	}
 	const squad = store.loadSquad(squadId);
 	if (!squad) {
 		ctx.ui.notify(`Squad '${squadId}' not found`, "error");
 		return;
 	}
 
-	activeSquadId = squadId;
-
-	// Update widget to show the new squad. The widget reads squadId on each
-	// render, so just updating the state and requesting a render is enough.
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	// Selection is one atomic focus operation: panel, widget, status, and tools
+	// must all target this exact squad before control returns to the caller.
+	focusSquad(squadId);
 
 	// Compact notification — widget already shows full task details.
 	// Avoid large multi-line notifications that can break TUI layout.
@@ -1660,6 +1711,9 @@ function forceWidgetUpdate(): void {
 /** Wire one scheduler to durable main-session notifications. */
 function wireSchedulerEvents(pi: ExtensionAPI, scheduler: Scheduler, squadId: string): void {
 	scheduler.onEvent((event: SchedulerEvent) => {
+		// Durable scheduler state remains authoritative, but disabled mode suppresses
+		// late operational UI, acknowledgements, focus, and ordinary notifications.
+		if (!squadEnabled) return;
 		forceWidgetUpdate();
 		switch (event.type) {
 			case "squad_review_required": {
@@ -1742,19 +1796,43 @@ function openPanel(
 	scheduler: Scheduler,
 	squadId: string,
 ): void {
+	if (!squadEnabled) {
+		ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+		return;
+	}
 	if (overlayOpen) return;
+	// Opening details also establishes authoritative focus. This covers callers
+	// that reconstructed or targeted a scheduler without going through selector UI.
+	focusSquad(squadId);
 	overlayOpen = true;
 
 	// The promise resolves when the panel calls done()
 	const panelPromise = ctx.ui.custom<SquadPanelResult>(
 		(tui, theme, _kb, done) => {
-			const panel = new SquadPanel(tui, theme, scheduler, squadId, done);
+			const panel = new SquadPanel(
+				tui,
+				theme,
+				scheduler,
+				squadId,
+				done,
+				() => squadEnabled,
+				() => ctx.ui.notify(DISABLED_GUIDANCE, "warning"),
+			);
+			closeOverlay = () => panel.close();
 
 			// Wire up message sending from panel
 			panel.onSendMessage = async (taskId: string, _prefill: string) => {
+				if (!squadEnabled) {
+					ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+					return;
+				}
 				const task = store.loadTask(squadId, taskId);
 				const agentName = task?.agent || taskId;
 				const input = await ctx.ui.input(`Message to ${agentName}`, "Type your message...");
+				if (!squadEnabled) {
+					ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+					return;
+				}
 				if (input) {
 					let panelSched = schedulers.get(squadId);
 					if (!panelSched) {
@@ -1788,9 +1866,11 @@ function openPanel(
 	// When panel closes (done() called), clean up
 	panelPromise.then(() => {
 		overlayOpen = false;
+		closeOverlay = null;
 		forceWidgetUpdate();
 	}).catch(() => {
 		overlayOpen = false;
+		closeOverlay = null;
 	});
 }
 
@@ -1841,6 +1921,10 @@ async function startSquad(
 		}
 	}
 
+	// A planner may take long enough for /squad disable to run concurrently.
+	// Re-check before publishing any squad or constructing a scheduler.
+	if (!squadEnabled) return disabledToolResult();
+
 	// Merge agent roster
 	const agents: Record<string, SquadAgentEntry> = { ...plan.agents };
 	if (params.agents) {
@@ -1914,12 +1998,8 @@ async function startSquad(
 	// Start scheduler
 	const scheduler = new Scheduler(squadId, skillPaths, schedulerSpawnContext);
 	schedulers.set(squadId, scheduler);
-	activeSquadId = squadId;
-
-	// Activate widget for this squad
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	// Activate panel/widget/tool focus as one invariant.
+	focusSquad(squadId);
 
 	// Wire up completion/escalation notifications to main agent.
 	wireSchedulerEvents(pi, scheduler, squadId);

package/src/panel/squad-panel.ts

@@ -41,6 +41,8 @@ export class SquadPanel implements Component, Focusable {
 	private done: (result: SquadPanelResult) => void;
 	private scheduler: Scheduler;
 	private squadId: string;
+	private isEnabled: () => boolean;
+	private onDisabled: () => void;
 
 	/** Callback for sending messages — set by the extension */
 	onSendMessage?: (taskId: string, message: string) => Promise<void>;
@@ -69,12 +71,16 @@ export class SquadPanel implements Component, Focusable {
 		scheduler: Scheduler,
 		squadId: string,
 		done: (result: SquadPanelResult) => void,
+		isEnabled: () => boolean = () => true,
+		onDisabled: () => void = () => {},
 	) {
 		this.tui = tui;
 		this.theme = theme;
 		this.scheduler = scheduler;
 		this.squadId = squadId;
 		this.done = done;
+		this.isEnabled = isEnabled;
+		this.onDisabled = onDisabled;
 
 		this.taskListView = new TaskListView(theme, squadId);
 		this.messageView = new MessageView(theme, squadId);
@@ -112,6 +118,12 @@ export class SquadPanel implements Component, Focusable {
 	// =========================================================================
 
 	handleInput(data: string): void {
+		if (!this.isEnabled()) {
+			this.onDisabled();
+			this.finish({ action: "close" });
+			return;
+		}
+
 		// Ctrl+Q or q: close panel
 		if (data === "\x11") {
 			this.finish({ action: "close" });
@@ -316,6 +328,10 @@ export class SquadPanel implements Component, Focusable {
 	// Lifecycle
 	// =========================================================================
 
+	close(): void {
+		this.finish({ action: "close" });
+	}
+
 	dispose(): void {
 		if (this.renderTimeout) {
 			clearTimeout(this.renderTimeout);

package/src/panel/squad-widget.ts

@@ -43,6 +43,12 @@ export interface SquadWidgetState {
 	enabled: boolean;
 }
 
+export interface SquadWidgetControls {
+	requestUpdate: () => void;
+	refreshNow: () => void;
+	dispose: () => void;
+}
+
 /**
  * Set up the squad widget. Returns control functions.
  *
@@ -53,11 +59,8 @@ export interface SquadWidgetState {
 export function setupSquadWidget(
 	ctx: { ui: { setWidget: Function; setStatus: Function; [key: string]: any }; hasUI?: boolean },
 	state: SquadWidgetState,
-): {
-	requestUpdate: () => void;
-	dispose: () => void;
-} {
-	if (!ctx.hasUI) return { requestUpdate: () => {}, dispose: () => {} };
+): SquadWidgetControls {
+	if (!ctx.hasUI) return { requestUpdate: () => {}, refreshNow: () => {}, dispose: () => {} };
 
 	let durationTimer: ReturnType<typeof setInterval> | null = null;
 	let renderTimer: ReturnType<typeof setTimeout> | null = null;
@@ -269,9 +272,14 @@ export function setupSquadWidget(
 		}
 	}
 
+	function refreshNow(): void {
+		if (renderTimer) { clearTimeout(renderTimer); renderTimer = null; }
+		render();
+		manageDurationTimer();
+	}
+
 	// Initial render
-	render();
-	manageDurationTimer();
+	refreshNow();
 
 	return {
 		requestUpdate(): void {
@@ -279,14 +287,17 @@ export function setupSquadWidget(
 			if (renderTimer) return;
 			renderTimer = setTimeout(() => {
 				renderTimer = null;
-				render();
-				manageDurationTimer();
+				refreshNow();
 			}, 50);
 		},
+		refreshNow,
 		dispose(): void {
 			if (durationTimer) { clearInterval(durationTimer); durationTimer = null; }
 			if (renderTimer) { clearTimeout(renderTimer); renderTimer = null; }
 			lastCacheKey = "";
+			currentLines = [];
+			widgetInstalled = false;
+			widgetComponent = null;
 			ctx.ui.setWidget("squad-tasks", undefined);
 			ctx.ui.setStatus("squad", undefined);
 		},

package/src/store.ts

@@ -62,12 +62,14 @@ export function getSquadSettingsPath(): string {
 	return path.join(SQUAD_HOME, "settings.json");
 }
 
-/** Load global squad settings, merged over defaults (advisor merged deep) */
+/** Load global squad settings, merged over defaults (advisor merged deep). */
 export function loadSquadSettings(): SquadSettings {
 	const loaded = readJson<Partial<SquadSettings>>(getSquadSettingsPath());
 	return {
 		...DEFAULT_SQUAD_SETTINGS,
 		...(loaded || {}),
+		// Legacy, missing, and malformed values remain backward-compatible.
+		enabled: typeof loaded?.enabled === "boolean" ? loaded.enabled : DEFAULT_SQUAD_SETTINGS.enabled,
 		advisor: { ...DEFAULT_SQUAD_SETTINGS.advisor, ...(loaded?.advisor || {}) },
 	};
 }

package/src/types.ts

@@ -44,6 +44,7 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
  * - any other string: an explicit model id (defaultModel) or thinking level (defaultThinking)
  */
 export interface SquadSettings {
+	enabled: boolean;
 	defaultModel: string;
 	defaultThinking: string;
 	advisor: {
@@ -56,6 +57,7 @@ export interface SquadSettings {
 }
 
 export const DEFAULT_SQUAD_SETTINGS: SquadSettings = {
+	enabled: true,
 	defaultModel: "main",
 	defaultThinking: "main",
 	advisor: {