@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/commands/deep-interview.ts

@@ -8,6 +8,7 @@ export default class DeepInterview extends Command {
 		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
 		standard: Flags.boolean({ description: "Seed a standard deep-interview run" }),
 		deep: Flags.boolean({ description: "Seed a deep deep-interview run" }),
+		trace: Flags.boolean({ description: "Run a bounded trace evidence pre-step before interview questions" }),
 		threshold: Flags.string({ description: "Override ambiguity threshold for kickoff" }),
 		"threshold-source": Flags.string({ description: "Describe the threshold override source" }),
 		"session-id": Flags.string({
@@ -25,7 +26,7 @@ export default class DeepInterview extends Command {
 		json: Flags.boolean({ description: "Output JSON" }),
 	};
 	static examples = [
-		'$ skc deep-interview --standard "<idea>"',
+		'$ skc deep-interview --trace --standard "<idea>"',
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
 	];

package/src/config/file-lock.ts

@@ -1,3 +1,4 @@
+import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import { isEnoent } from "@sayknow-cli/utils/fs-error";
 
@@ -22,9 +23,10 @@ function getLockPath(filePath: string): string {
 	return `${filePath}.lock`;
 }
 
-async function writeLockInfo(lockPath: string): Promise<void> {
+async function writeLockInfo(lockPath: string): Promise<LockInfo> {
 	const info: LockInfo = { pid: process.pid, timestamp: Date.now() };
 	await Bun.write(`${lockPath}/info`, JSON.stringify(info));
+	return info;
 }
 
 async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
@@ -51,17 +53,30 @@ export interface FileLockOwnerToken {
 	timestamp: number;
 }
 
-/** Outcome of a guarded GC removal attempt (`removeFileLockDirForGc`). */
+/** Outcome of a guarded lock-dir removal attempt (`removeFileLockDirForGc`). */
 export type FileLockGcRemoval = "removed" | "owner_changed" | "missing";
 
+interface LockDirStatToken {
+	dev: number;
+	ino: number;
+	mtimeMs: number;
+	ctimeMs: number;
+}
+
+type LockStaleSnapshot =
+	| { stale: false }
+	| { stale: true; owner: FileLockOwnerToken }
+	| { stale: true; owner: null; stat: LockDirStatToken };
+
 /**
  * @internal
- * Fail-closed removal of a dead lock dir for GC. Re-reads the on-disk owner
- * token as close to the unlink as possible and only deletes the dir when it
- * STILL holds the exact `{pid, timestamp}` identity the caller observed dead.
+ * Fail-closed removal of a lock dir whose owner is expected to be dead or
+ * finished. Re-reads the on-disk owner token as close to the unlink as possible
+ * and only deletes the dir when it STILL holds the exact `{pid, timestamp}`
+ * identity the caller observed.
  *
- * Closes the prune-time TOCTOU window (#606): between GC's dead re-read/probe
- * and the unlink, a live process can reclaim a stale lock at the same path
+ * Closes stale-cleanup TOCTOU windows (#606): between a dead/stale re-read and
+ * the unlink, a live process can reclaim a stale lock at the same path
  * (`acquireLock` rms the stale dir, then re-`mkdir`s and rewrites `info` with a
  * fresh pid+timestamp). Deleting by path alone would reap that LIVE lock. Any
  * mismatch (`owner_changed`) or absent/unreadable info (`missing` — e.g. a
@@ -99,14 +114,28 @@ function ownerLiveness(pid: number): OwnerLiveness {
 	}
 }
 
-async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
+function statToken(stats: Stats): LockDirStatToken {
+	return {
+		dev: stats.dev,
+		ino: stats.ino,
+		mtimeMs: stats.mtimeMs,
+		ctimeMs: stats.ctimeMs,
+	};
+}
+
+function sameStatToken(a: LockDirStatToken, b: LockDirStatToken): boolean {
+	return a.dev === b.dev && a.ino === b.ino && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+async function staleLockSnapshot(lockPath: string, staleMs: number): Promise<LockStaleSnapshot> {
 	const info = await readLockInfo(lockPath);
 	if (!info) {
 		try {
 			const stats = await fs.stat(lockPath);
-			return Date.now() - stats.mtimeMs > staleMs;
+			if (Date.now() - stats.mtimeMs <= staleMs) return { stale: false };
+			return { stale: true, owner: null, stat: statToken(stats) };
 		} catch (err) {
-			if (isEnoent(err)) return false;
+			if (isEnoent(err)) return { stale: false };
 			throw err;
 		}
 	}
@@ -115,53 +144,63 @@ async function isLockStale(lockPath: string, staleMs: number): Promise<boolean>
 	// not have its lock stolen (#652). Reclaim a dead owner immediately. Only when owner
 	// liveness is indeterminate do we fall back to the staleMs elapsed-time heuristic.
 	const liveness = ownerLiveness(info.pid);
-	if (liveness === "dead") return true;
-	if (liveness === "alive") return false;
-	return Date.now() - info.timestamp > staleMs;
+	if (liveness === "alive") return { stale: false };
+	if (liveness === "dead" || Date.now() - info.timestamp > staleMs) {
+		return { stale: true, owner: { pid: info.pid, timestamp: info.timestamp } };
+	}
+	return { stale: false };
 }
 
-async function tryAcquireLock(lockPath: string): Promise<boolean> {
+async function removeStaleLockForAcquire(lockPath: string, snapshot: LockStaleSnapshot): Promise<boolean> {
+	if (!snapshot.stale) return false;
+	if (snapshot.owner) {
+		return (await removeFileLockDirForGc(lockPath, snapshot.owner)) === "removed";
+	}
+
+	const currentInfo = await readLockInfo(lockPath);
+	if (currentInfo) return false;
 	try {
-		await fs.mkdir(lockPath);
-		await writeLockInfo(lockPath);
+		const currentStats = await fs.stat(lockPath);
+		if (!sameStatToken(statToken(currentStats), snapshot.stat)) return false;
+		await fs.rm(lockPath, { recursive: true, force: true });
 		return true;
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
+}
+
+async function tryAcquireLock(lockPath: string): Promise<LockInfo | null> {
+	try {
+		await fs.mkdir(lockPath);
+		return await writeLockInfo(lockPath);
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-			return false;
+			return null;
 		}
 		throw error;
 	}
 }
 
-async function releaseLock(lockPath: string): Promise<void> {
+async function releaseLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
 	try {
-		await fs.rm(lockPath, { recursive: true });
+		await removeFileLockDirForGc(lockPath, owner);
 	} catch {
 		// Ignore errors on release
 	}
 }
-
-async function lockExists(lockPath: string): Promise<boolean> {
-	try {
-		await fs.stat(lockPath);
-		return true;
-	} catch (err) {
-		if (isEnoent(err)) return false;
-		throw err;
-	}
-}
-
 async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 	const lockPath = getLockPath(filePath);
 
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
-		if (await tryAcquireLock(lockPath)) {
-			return () => releaseLock(lockPath);
+		const owner = await tryAcquireLock(lockPath);
+		if (owner) {
+			return () => releaseLock(lockPath, owner);
 		}
 
-		if ((await lockExists(lockPath)) && (await isLockStale(lockPath, opts.staleMs))) {
-			await releaseLock(lockPath);
+		const stale = await staleLockSnapshot(lockPath, opts.staleMs);
+		if (await removeStaleLockForAcquire(lockPath, stale)) {
 			continue;
 		}
 

package/src/config/keybindings.ts

@@ -134,8 +134,8 @@ export const KEYBINDINGS = {
 		description: "Queue message for next turn",
 	},
 	"app.message.dequeue": {
-		defaultKeys: "alt+up",
-		description: "Dequeue message",
+		defaultKeys: ["alt+up", "alt+down"],
+		description: "Select queued message to edit",
 	},
 	"app.clipboard.pasteImage": {
 		defaultKeys: process.platform === "win32" ? "alt+v" : "ctrl+v",

package/src/config/model-profile-activation.ts

@@ -76,6 +76,34 @@ export interface MaterializeModelProfileAssignmentOptions {
 	selector: string;
 }
 
+export interface MaterializeModelProfileAssignmentsOptions {
+	session: Pick<
+		ModelProfileActivationSession,
+		"model" | "thinkingLevel" | "setActiveModelProfile" | "getActiveModelProfile"
+	>;
+	settings: Pick<Settings, "clearOverride" | "get" | "override" | "set">;
+	assignments: ReadonlyMap<SkcModelAssignmentTargetId, string> | Partial<Record<SkcModelAssignmentTargetId, string>>;
+}
+
+function isReadonlyAssignmentMap(
+	assignments: ReadonlyMap<SkcModelAssignmentTargetId, string> | Partial<Record<SkcModelAssignmentTargetId, string>>,
+): assignments is ReadonlyMap<SkcModelAssignmentTargetId, string> {
+	return typeof (assignments as { entries?: unknown }).entries === "function";
+}
+
+function getMaterializedAssignments(
+	assignments: ReadonlyMap<SkcModelAssignmentTargetId, string> | Partial<Record<SkcModelAssignmentTargetId, string>>,
+): Array<[SkcModelAssignmentTargetId, string]> {
+	if (isReadonlyAssignmentMap(assignments)) return [...assignments.entries()];
+	const assignmentRecord: Partial<Record<SkcModelAssignmentTargetId, string>> = assignments;
+	const result: Array<[SkcModelAssignmentTargetId, string]> = [];
+	for (const role of Object.keys(assignmentRecord) as SkcModelAssignmentTargetId[]) {
+		const selector = assignmentRecord[role];
+		if (selector !== undefined) result.push([role, selector]);
+	}
+	return result;
+}
+
 export function materializeActiveModelProfileAssignment(options: MaterializeModelProfileAssignmentOptions): boolean {
 	const activeProfile = options.session.getActiveModelProfile?.() ?? options.settings.get("modelProfile.default");
 	if (!activeProfile) return false;
@@ -109,6 +137,43 @@ export function materializeActiveModelProfileAssignment(options: MaterializeMode
 	return true;
 }
 
+export function materializeActiveModelProfileAssignments(options: MaterializeModelProfileAssignmentsOptions): boolean {
+	const activeProfile = options.session.getActiveModelProfile?.() ?? options.settings.get("modelProfile.default");
+	if (!activeProfile) return false;
+
+	const materializedAssignments = getMaterializedAssignments(options.assignments);
+	if (materializedAssignments.length === 0) return true;
+
+	const nextModelRoles = { ...options.settings.get("modelRoles") };
+	const nextAgentModelOverrides = { ...options.settings.get("task.agentModelOverrides") };
+	const includesDefault = materializedAssignments.some(([role]) => role === "default");
+
+	if (!includesDefault && !nextModelRoles.default && options.session.model) {
+		nextModelRoles.default = formatModelSelectorValue(
+			`${options.session.model.provider}/${options.session.model.id}`,
+			options.session.thinkingLevel,
+		);
+	}
+
+	for (const [role, selector] of materializedAssignments) {
+		const target = SKC_MODEL_ASSIGNMENT_TARGETS[role];
+		if (target.settingsPath === "modelRoles") {
+			nextModelRoles[role] = selector;
+		} else {
+			nextAgentModelOverrides[role] = selector;
+		}
+	}
+
+	options.settings.set("modelRoles", nextModelRoles);
+	options.settings.set("task.agentModelOverrides", nextAgentModelOverrides);
+	options.settings.set("modelProfile.default", undefined);
+	options.settings.clearOverride("modelProfile.default");
+	options.settings.override("modelRoles", nextModelRoles);
+	options.settings.override("task.agentModelOverrides", nextAgentModelOverrides);
+	options.session.setActiveModelProfile?.(undefined);
+	return true;
+}
+
 export function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string {
 	return `Model profile "${profileName}" requires credentials for: ${providers.join(", ")}. Run /login and configure the missing provider(s), then retry.`;
 }

package/src/config/model-profiles.ts

@@ -1,3 +1,4 @@
+import { sanitizeText } from "@sayknow-cli/utils";
 import type { SkcModelAssignmentTargetId } from "./model-registry";
 import type { ModelsConfig } from "./models-config-schema";
 
@@ -98,11 +99,18 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 	}),
 	profile("claude-opus", ["anthropic"], {
 		default: "anthropic/claude-opus-4-8:xhigh",
-		executor: "anthropic/claude-sonnet-4-6",
+		executor: "anthropic/claude-sonnet-5",
 		planner: "anthropic/claude-opus-4-8:low",
 		critic: "anthropic/claude-opus-4-8:high",
 		architect: "anthropic/claude-opus-4-8:xhigh",
 	}),
+	profile("claude-fable", ["anthropic"], {
+		default: "anthropic/claude-fable-5:xhigh",
+		executor: "anthropic/claude-sonnet-5",
+		planner: "anthropic/claude-fable-5:low",
+		critic: "anthropic/claude-fable-5:high",
+		architect: "anthropic/claude-fable-5:xhigh",
+	}),
 	profile("glm-eco", ["zai"], {
 		default: "zai/glm-5.2:low",
 		executor: "zai/glm-5.2:minimal",
@@ -260,6 +268,13 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 		critic: "opencode-go/mimo-v2.5-pro",
 		architect: "openai-codex/gpt-5.5:xhigh",
 	}),
+	profile("fable-opus-codex", ["anthropic", "openai-codex"], {
+		default: "anthropic/claude-fable-5:high",
+		executor: "openai-codex/gpt-5.5:high",
+		planner: "anthropic/claude-opus-4-8:medium",
+		critic: "anthropic/claude-opus-4-8:high",
+		architect: "openai-codex/gpt-5.5:xhigh",
+	}),
 ];
 
 export interface ModelProfilePresentation {
@@ -267,12 +282,17 @@ export interface ModelProfilePresentation {
 	providerGroup: string;
 }
 
+function sanitizeModelProfileLabel(value: string): string {
+	return sanitizeText(value).replace(/\s+/g, " ").trim();
+}
+
 const PROFILE_PRESENTATION: Record<string, ModelProfilePresentation> = {
 	"codex-eco": { displayName: "Codex Eco", providerGroup: "CODEX" },
 	"codex-medium": { displayName: "Codex Medium", providerGroup: "CODEX" },
 	"codex-pro": { displayName: "Codex Pro", providerGroup: "CODEX" },
 	opencodego: { displayName: "OpenCodeGo", providerGroup: "OPENCODEGO" },
 	"claude-opus": { displayName: "Claude Opus", providerGroup: "CLAUDE" },
+	"claude-fable": { displayName: "Claude Fable", providerGroup: "CLAUDE" },
 	"glm-eco": { displayName: "GLM Eco", providerGroup: "GLM" },
 	"glm-medium": { displayName: "GLM Medium", providerGroup: "GLM" },
 	"glm-pro": { displayName: "GLM Pro", providerGroup: "GLM" },
@@ -294,6 +314,7 @@ const PROFILE_PRESENTATION: Record<string, ModelProfilePresentation> = {
 	"minimax-pro": { displayName: "MiniMax Pro", providerGroup: "MINIMAX" },
 	"opus-codex": { displayName: "Opus + Codex", providerGroup: "COMBOS" },
 	"codex-opencodego": { displayName: "Codex + OpenCodeGo", providerGroup: "COMBOS" },
+	"fable-opus-codex": { displayName: "Fable + Opus + Codex", providerGroup: "COMBOS" },
 };
 
 const PROFILE_GROUP_ORDER = [
@@ -332,7 +353,15 @@ export function getModelProfilePresentation(
 	const displayName = typeof profile === "string" ? undefined : profile.displayName;
 	const presentation = PROFILE_PRESENTATION[name];
 	if (presentation) return presentation;
-	return { displayName: displayName ?? name, providerGroup: "CUSTOM" };
+	return { displayName: formatModelProfileDisplayLabel({ name, displayName }), providerGroup: "CUSTOM" };
+}
+
+export function formatModelProfileDisplayLabel(profile: Pick<ModelProfileDefinition, "name" | "displayName">): string {
+	return (
+		sanitizeModelProfileLabel(profile.displayName ?? profile.name) ||
+		sanitizeModelProfileLabel(profile.name) ||
+		"Unnamed profile"
+	);
 }
 
 export function groupModelProfilesForPresetLanding(

package/src/config/settings-schema.ts

@@ -570,6 +570,42 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
+
+	"tools.readArtifactSpillThreshold": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tools",
+			label: "Experimental read-tool artifact spill threshold (KB)",
+			description:
+				"Advanced opt-in only: combined-size cap for `read` output across all requested ranges. Above this the full output is saved as an artifact and a bounded head+tail snippet is kept inline. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 found no token savings and a lower cache-hit rate at 50 KB, so normal coding sessions should leave this Off unless intentionally measuring large-read behavior.",
+			options: [
+				{ value: "0", label: "Off", description: "Default; no read-specific spill (backstop only)" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+				{ value: "100", label: "100 KB", description: "~25K tokens" },
+				{ value: "256", label: "256 KB", description: "~64K tokens" },
+				{ value: "512", label: "512 KB", description: "~128K tokens" },
+				{ value: "1000", label: "1 MB", description: "~250K tokens" },
+			],
+		},
+	},
+
+	"tools.fileMentionInlineBytes": {
+		type: "number",
+		default: 20,
+		ui: {
+			tab: "tools",
+			label: "File-mention inline cap (KB)",
+			description:
+				"Inline byte cap for auto-read `@path` file mentions, deliberately below the read-tool cap so an incidental mention injects a smaller snippet than an explicit read. The full file is still available via the read tool.",
+			options: [
+				{ value: "5", label: "5 KB", description: "~1.25K tokens" },
+				{ value: "10", label: "10 KB", description: "~2.5K tokens" },
+				{ value: "20", label: "20 KB", description: "Default; ~5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens (matches read cap)" },
+			],
+		},
+	},
 	"tools.artifactTailBytes": {
 		type: "number",
 		default: 20,
@@ -648,6 +684,25 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"tools.maxInlineResultBytes": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tools",
+			label: "Max inline tool-result size (KB)",
+			description:
+				"Absolute backstop cap on inline tool-result text, enforced after artifact spill for every tool (including read and tools that set their own partial artifact meta). Output above this size is force-saved as an artifact and truncated to head+tail. 0 disables (default; opt-in pending measurement).",
+			options: [
+				{ value: "0", label: "Off", description: "Disabled; no absolute inline cap" },
+				{ value: "20", label: "20 KB", description: "~5K tokens" },
+				{ value: "30", label: "30 KB", description: "~7.5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+				{ value: "75", label: "75 KB", description: "~19K tokens" },
+				{ value: "100", label: "100 KB", description: "~25K tokens" },
+			],
+		},
+	},
+
 	"statusLine.showHookStatus": {
 		type: "boolean",
 		default: false,
@@ -1410,6 +1465,15 @@ export const SETTINGS_SCHEMA = {
 
 	"compaction.remoteEndpoint": { type: "string", default: undefined },
 
+	// Below-threshold maintenance pruning (Finding 13). Internal/measurement-only:
+	// keep the runtime setting for targeted experiments, but do not expose it in
+	// settings UI. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 showed no
+	// savings and a cache-hit regression; pruning rewrites already-sent history and
+	// can force a provider cache-epoch reset.
+	"compaction.maintenancePruningEnabled": { type: "boolean", default: false },
+
+	"compaction.maintenancePruningMinSavingsTokens": { type: "number", default: 8000 },
+
 	// Idle compaction
 	"compaction.idleEnabled": {
 		type: "boolean",
@@ -1683,7 +1747,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "context",
 			label: "TTSR Context Mode",
-			description: "What to do with partial output when TTSR triggers",
+			description:
+				"What to do with partial output when TTSR triggers. 'discard' (recommended) drops the aborted partial turn so it never accumulates in context. 'keep' retains every aborted partial turn, which grows the token footprint each time a rule fires — prefer 'discard' unless you specifically need the partial output.",
 		},
 	},
 
@@ -3421,6 +3486,8 @@ export interface CompactionSettings {
 	autoContinue: boolean;
 	remoteEnabled: boolean;
 	remoteEndpoint: string | undefined;
+	maintenancePruningEnabled: boolean;
+	maintenancePruningMinSavingsTokens: number;
 	idleEnabled: boolean;
 	idleThresholdTokens: number;
 	idleTimeoutSeconds: number;

package/src/config/settings.ts

@@ -476,6 +476,28 @@ export class Settings {
 			this.override("modelRoles", { ...shallowStringRecord(runtimeOverrides), [role]: modelId });
 		}
 	}
+	/**
+	 * Set an agent model override while keeping any live runtime override aligned.
+	 *
+	 * Runtime model profiles override `task.agentModelOverrides` for the current
+	 * session. A user-selected role assignment must win immediately in that same
+	 * session, but only the explicit agent change should be persisted.
+	 */
+	setAgentModelOverride(agentName: string, modelId: string): void {
+		const current = shallowStringRecord(getByPath(this.#global, ["task", "agentModelOverrides"]));
+		const runtimeOverrides = getByPath(this.#overrides, ["task", "agentModelOverrides"]);
+		const updateRuntimeOverride =
+			!!runtimeOverrides && typeof runtimeOverrides === "object" && !Array.isArray(runtimeOverrides);
+
+		this.set("task.agentModelOverrides", { ...current, [agentName]: modelId });
+
+		if (updateRuntimeOverride) {
+			this.override("task.agentModelOverrides", {
+				...shallowStringRecord(runtimeOverrides),
+				[agentName]: modelId,
+			});
+		}
+	}
 
 	/**
 	 * Get a model role (helper for modelRoles record).

package/src/defaults/skc/skills/team/SKILL.md

@@ -112,7 +112,7 @@ Before launching `skc team`, require a grounded context snapshot:
    - unknowns/open questions
    - likely codebase touchpoints
 4. If ambiguity remains high, gather brownfield facts with focused repo inspection or a canonical read-only role agent first, then run `$deep-interview --quick <task>` before team launch.
-5. If current correctness depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, auto-delegate `researcher` as an evidence lane before or alongside worker launch instead of relying on repo-local recall alone.
+5. If current correctness depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, gather evidence before or alongside worker launch using supported surfaces only: focused repo inspection for local facts, `planner` for broad context mapping/sequencing, `architect` for architecture or external-doc-risk assessment, and direct web/search tools when configured.
 
 Do not start the worker pane until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.
 
@@ -343,14 +343,15 @@ Use only after checking `skc team status <team>` and state evidence:
    - `.skc/_session-{sessionid}/state/team/<team>/config.json`
    - `.skc/_session-{sessionid}/state/team/<team>/tasks/task-1.json`
    - `.skc/_session-{sessionid}/state/team/<team>/mailbox/worker-1.json`
-2. Capture pane tail to confirm current worker state:
-   - `tmux capture-pane -t %<worker-pane> -p -S -120`
-   - If a larger-tail read or bounded summary would help, prefer explicit opt-in inspection via `skc sparkshell --tmux-pane %<worker-pane> --tail-lines 400` before improvising extra tmux commands.
-3. If the pane is stuck in an interactive state, safely return to idle prompt first:
-   - optional interrupt `C-c` or escape flow (CLI-specific) once, then re-check pane capture
+2. Use supported team surfaces before manual pane intervention:
+   - `skc team status <team>` for current recorded state
+   - `skc team monitor <team>` when a live monitor/update loop is needed
+   - `skc team api <team>` only for documented programmatic operations
+3. If the recorded worker pane is stuck in an interactive state, safely return to idle prompt first:
+   - optional interrupt `C-c` or escape flow (CLI-specific) once, then re-check `skc team status <team>` and relevant state files
 4. Send one concise trigger only when runtime/state checks show manual prompt input is needed:
    - `tmux send-keys -t %<worker-pane> "continue current task; report status" C-m`
-5. Re-check pane output, task state, worker mailbox, and `skc team status <team>`.
+5. Re-check task state, worker mailbox, and `skc team status <team>`.
 
 ### Shutdown reports success but stale worker panes remain
 
@@ -372,8 +373,9 @@ tmux list-panes -F '#{pane_id}	#{pane_current_command}	#{pane_start_command}'
 tmux kill-pane -t %450
 tmux kill-pane -t %451
 
-# 3) Remove stale team state only after preserving needed evidence, using the state runtime
-# cleanup verb documented by the current manifest
+# 3) Shut down recorded team state/workers through the supported team runtime
+# Replace <team-name> with the team from `skc team list` / `skc team status`.
+skc team shutdown <team-name>
 
 # 4) Retry
 skc team executor "fresh retry"
@@ -396,7 +398,7 @@ When operating this skill, provide concrete progress evidence:
 
 Do not claim success without file/pane evidence.
 Do not claim clean completion if shutdown occurred with `in_progress>0`.
-Use `skc sparkshell --tmux-pane ...` as an explicit opt-in operator aid for pane inspection and summaries; keep raw `tmux capture-pane` evidence available for manual intervention and proof.
+Use `skc team status <team>` and `skc team monitor <team>` as the supported operator aids for status inspection; keep raw state-file or pane evidence available for manual intervention and proof.
 
 ## Programmatic Team Orchestration
 
@@ -405,14 +407,15 @@ Use the `skc team ...` CLI as the supported team-launch surface. For automation,
 ### Supported current surfaces
 
 - **`skc team ...` CLI** — Primary method for interactive or automated team orchestration. Use this when you want direct tmux-pane visibility or a scriptable launch path.
+- **`skc team status <team>`** — Read current team/task/worker state.
+- **`skc team monitor <team>`** — Follow live progress through the supported runtime surface.
+- **`skc team shutdown <team>`** — Stop recorded active workers and move the team toward terminal state.
+- **`skc team api <team>`** — Use only for documented programmatic operations exposed by the team runtime.
 - **Team state files** — Inspect `.skc/_session-{sessionid}/state/team/<team>/` when you need status, task, or mailbox evidence after launch.
 
 ### Cleanup distinction
 
-Two cleanup paths exist and must not be confused:
-
-- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.skc/_session-{sessionid}/state/team/<team>/`). Use after a team run is fully complete.
-- tmux/session cleanup: Use the documented `skc team` shutdown / cleanup flow when you need to stop the worker pane or clean up an interrupted run.
+Use `skc team shutdown <team>` for recorded active workers. After shutdown reports a terminal state and required evidence is preserved, use supported `skc state ...` session/mode cleanup commands only when you are intentionally clearing state; do not delete team state by hand during an active run. Use manual tmux/session cleanup only for verified stale panes that are not handled by the documented shutdown flow.
 
 ### Automation example