@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/session/streaming-output.ts

@@ -54,6 +54,10 @@ export interface OutputSummary {
 }
 
 export interface OutputSinkOptions {
+	/**
+	 * Deprecated managed artifact pathname. Bare paths are deliberately ignored:
+	 * streaming output must be terminally published through ArtifactManager.
+	 */
 	artifactPath?: string;
 	artifactId?: string;
 	/** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
@@ -736,6 +740,8 @@ export class OutputSink {
 			artifactMaxBytes = DEFAULT_ARTIFACT_MAX_BYTES,
 			coalesceSanitize = process.env.PI_OUTPUT_SANITIZE_COALESCE === "1",
 		} = options ?? {};
+		// Managed callers omit artifactPath at the allocation boundary; explicit callers
+		// retain the existing pathname-backed streaming contract.
 		this.#artifactPath = artifactPath;
 		this.#artifactId = artifactId;
 		this.#spillThreshold = spillThreshold;

package/src/session/volatile-context-pruning.ts

@@ -0,0 +1,78 @@
+import type { CustomMessageEntry, SessionEntry } from "./session-manager";
+
+const SUPERSEDED_VOLATILE_CONTEXT_NOTICE = "[superseded volatile context pruned]";
+
+/**
+ * Custom messages whose producer maintains one current singleton state:
+ * - todo-write-error-reminder: a later todo-write failure replaces the prior warning.
+ * - resolve-reminder: only the currently pending resolve preview can be applied.
+ * - eager-todo-prelude: the newest todo prelude reflects the current task state.
+ */
+const SUPERSEDED_SINGLETON_REMINDER_TYPES = new Set([
+	"todo-write-error-reminder",
+	"resolve-reminder",
+	"eager-todo-prelude",
+]);
+
+/**
+ * Volatile context is refreshed for every prompt. Only its newest copy is useful;
+ * replacing older copies at a maintenance boundary preserves the audit trail
+ * without repeatedly charging the model for stale workspace snapshots.
+ */
+export function pruneSupersededVolatileProjectContext(entries: readonly SessionEntry[]): {
+	changed: CustomMessageEntry[];
+	bytesSaved: number;
+} {
+	let latest = -1;
+	entries.forEach((entry, index) => {
+		if (entry.type === "custom_message" && entry.customType === "volatile-project-context") latest = index;
+	});
+	if (latest < 0) return { changed: [], bytesSaved: 0 };
+
+	const changed: CustomMessageEntry[] = [];
+	let bytesSaved = 0;
+	entries.forEach((entry, index) => {
+		if (index >= latest || entry.type !== "custom_message" || entry.customType !== "volatile-project-context") return;
+		const content =
+			typeof entry.content === "string"
+				? entry.content
+				: entry.content.map(block => (block.type === "text" ? block.text : "")).join("\n");
+		if (!content) return;
+		entry.content = SUPERSEDED_VOLATILE_CONTEXT_NOTICE;
+		bytesSaved += Buffer.byteLength(content, "utf-8");
+		changed.push(entry as CustomMessageEntry);
+	});
+	return { changed, bytesSaved };
+}
+
+/** Retire superseded known singleton maintenance reminders without touching ordinary user context. */
+export function pruneSupersededMaintenanceReminders(entries: readonly SessionEntry[]): {
+	changed: CustomMessageEntry[];
+	bytesSaved: number;
+} {
+	const latest = new Map<string, number>();
+	entries.forEach((entry, index) => {
+		if (entry.type === "custom_message" && SUPERSEDED_SINGLETON_REMINDER_TYPES.has(entry.customType)) {
+			latest.set(entry.customType, index);
+		}
+	});
+	const changed: CustomMessageEntry[] = [];
+	let bytesSaved = 0;
+	entries.forEach((entry, index) => {
+		if (
+			entry.type !== "custom_message" ||
+			latest.get(entry.customType) === undefined ||
+			latest.get(entry.customType) === index
+		)
+			return;
+		const text =
+			typeof entry.content === "string"
+				? entry.content
+				: entry.content.map(block => (block.type === "text" ? block.text : "")).join("\n");
+		if (!text) return;
+		entry.content = SUPERSEDED_VOLATILE_CONTEXT_NOTICE;
+		bytesSaved += Buffer.byteLength(text, "utf-8");
+		changed.push(entry);
+	});
+	return { changed, bytesSaved };
+}

package/src/session/yield-queue.ts

@@ -107,6 +107,26 @@ export class YieldQueue {
 		this.#idleFlushPending = false;
 	}
 
+	/** Drop only the queued entries of a single kind, leaving other kinds intact. */
+	clearKind(kind: string): void {
+		this.#entries.delete(kind);
+	}
+
+	/**
+	 * Re-schedule an idle flush if work remains and the session is idle. Used after
+	 * a transition (e.g. handoff) releases a delivery fence so entries queued while
+	 * fenced are not stranded until an unrelated enqueue or agent yield.
+	 */
+	rearmIdle(): void {
+		if (this.#options.isStreaming()) return;
+		for (const entries of this.#entries.values()) {
+			if (entries.length > 0) {
+				this.#scheduleIdleFlush();
+				return;
+			}
+		}
+	}
+
 	#scheduleIdleFlush(): void {
 		if (this.#idleFlushPending) return;
 		this.#idleFlushPending = true;

package/src/setup/credential-auto-import.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type {
@@ -7,8 +8,8 @@ import type {
 	AuthStorage,
 } from "@sayknow-cli/ai";
 import { getAgentDir, logger, VERSION } from "@sayknow-cli/utils";
+import { withFileLock } from "../config/file-lock";
 import type { ModelRegistry } from "../config/model-registry";
-
 import {
 	type CredentialDiscoveryResult,
 	type CredentialOrigin,
@@ -23,42 +24,207 @@ import {
 
 export const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING =
 	"Refreshing in skc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+export const CREDENTIAL_AUTO_IMPORT_PERSISTENCE_WARNING =
+	"Credential import preference could not be saved; external credentials may be offered again.";
+export const CREDENTIAL_AUTO_IMPORT_REFRESH_WARNING =
+	"Imported credentials were saved, but provider availability could not be refreshed.";
+export const CREDENTIAL_AUTO_IMPORT_DISCOVERY_WARNING =
+	"External credential discovery could not be completed. Use /provider to import credentials manually.";
+export const CREDENTIAL_AUTO_IMPORT_RETRY_WARNING =
+	"Some external credentials could not be imported. Use /provider to retry.";
+
+export const CREDENTIAL_AUTO_IMPORT_STATE_UNREADABLE_WARNING =
+	"Credential import preference could not be read. External credential discovery was skipped; use /provider to import credentials manually.";
 
 export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
 export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+export type InitialImportResolution = "accepted" | "declined";
+export type CredentialAutoImportStateProblem =
+	| "invalid-initial-import-resolution"
+	| "invalid-last-import-version"
+	| "malformed-json"
+	| "malformed-root";
 
 const CREDENTIAL_AUTO_IMPORT_STATE_FILENAME = "credential-auto-import-state.json";
+const VERSION_MARKER_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export interface CredentialAutoImportStateFile {
+	lastImportVersion?: string;
+	initialImportResolution?: InitialImportResolution;
+}
+
+export interface CredentialAutoImportStateReadResult {
+	state: CredentialAutoImportStateFile;
+	problems: CredentialAutoImportStateProblem[];
+	unreadable: boolean;
+}
 
-interface CredentialAutoImportStateFile {
-	lastImportVersion?: unknown;
+export interface CredentialAutoImportStateMutation {
+	lastImportVersion?: string;
+	initialImportResolution?: InitialImportResolution;
+}
+
+export interface CredentialAutoImportStateStore {
+	read: () => Promise<CredentialAutoImportStateReadResult>;
+	write: (mutation: CredentialAutoImportStateMutation) => Promise<boolean>;
+}
+
+export interface CredentialAutoImportStateStoreDependencies {
+	withFileLock?: <T>(filePath: string, transaction: () => Promise<T>) => Promise<T>;
+	rename?: (oldPath: string, newPath: string) => Promise<void>;
 }
 
 export function getCredentialAutoImportStatePath(agentDir: string = getAgentDir()): string {
 	return path.join(agentDir, CREDENTIAL_AUTO_IMPORT_STATE_FILENAME);
 }
 
-export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+function isEnoent(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}
+
+function isValidVersionMarker(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.trim() === value &&
+		value.length <= 128 &&
+		VERSION_MARKER_PATTERN.test(value)
+	);
+}
+
+function isInitialImportResolution(value: unknown): value is InitialImportResolution {
+	return value === "accepted" || value === "declined";
+}
+
+function projectCredentialAutoImportState(value: unknown): CredentialAutoImportStateReadResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return { state: {}, problems: ["malformed-root"], unreadable: false };
+	}
+
+	const record = value as Record<string, unknown>;
+	const state: CredentialAutoImportStateFile = {};
+	const problems: CredentialAutoImportStateProblem[] = [];
+	if (Object.hasOwn(record, "initialImportResolution")) {
+		if (isInitialImportResolution(record.initialImportResolution)) {
+			state.initialImportResolution = record.initialImportResolution;
+		} else {
+			problems.push("invalid-initial-import-resolution");
+		}
+	}
+	if (Object.hasOwn(record, "lastImportVersion")) {
+		if (isValidVersionMarker(record.lastImportVersion)) {
+			state.lastImportVersion = record.lastImportVersion;
+		} else {
+			problems.push("invalid-last-import-version");
+		}
+	}
+	return { state, problems, unreadable: false };
+}
+
+async function readCredentialAutoImportStateAtPath(statePath: string): Promise<CredentialAutoImportStateReadResult> {
 	try {
-		const raw = await fs.readFile(getCredentialAutoImportStatePath(agentDir), "utf-8");
-		const parsed = JSON.parse(raw) as CredentialAutoImportStateFile;
-		return typeof parsed.lastImportVersion === "string" ? parsed.lastImportVersion : undefined;
-	} catch {
-		return undefined;
+		const raw = await fs.readFile(statePath, "utf-8");
+		try {
+			return projectCredentialAutoImportState(JSON.parse(raw) as unknown);
+		} catch {
+			return { state: {}, problems: ["malformed-json"], unreadable: false };
+		}
+	} catch (error: unknown) {
+		if (isEnoent(error)) return { state: {}, problems: [], unreadable: false };
+		return { state: {}, problems: [], unreadable: true };
 	}
 }
 
-export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+function serializeCredentialAutoImportState(state: CredentialAutoImportStateFile): string {
+	const serialized: CredentialAutoImportStateFile = {};
+	if (isValidVersionMarker(state.lastImportVersion)) serialized.lastImportVersion = state.lastImportVersion;
+	if (isInitialImportResolution(state.initialImportResolution)) {
+		serialized.initialImportResolution = state.initialImportResolution;
+	}
+	return `${JSON.stringify(serialized)}\n`;
+}
+
+async function writeCredentialAutoImportStateAtomic(
+	statePath: string,
+	state: CredentialAutoImportStateFile,
+	rename: (oldPath: string, newPath: string) => Promise<void> = fs.rename,
+): Promise<void> {
+	const temporaryPath = `${statePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
 	try {
-		const statePath = getCredentialAutoImportStatePath(agentDir);
-		await fs.mkdir(path.dirname(statePath), { recursive: true });
-		await fs.writeFile(statePath, `${JSON.stringify({ lastImportVersion: version })}\n`);
-		return true;
+		const handle = await fs.open(temporaryPath, "wx", 0o600);
+		try {
+			await handle.writeFile(serializeCredentialAutoImportState(state));
+		} finally {
+			await handle.close();
+		}
+		await rename(temporaryPath, statePath);
 	} catch (error: unknown) {
-		logger.warn("Failed to persist credential auto-import state", { error });
-		return false;
+		await fs.rm(temporaryPath, { force: true }).catch(() => {});
+		throw error;
 	}
 }
 
+export function createCredentialAutoImportStateStore(
+	agentDir: string = getAgentDir(),
+	dependencies: CredentialAutoImportStateStoreDependencies = {},
+): CredentialAutoImportStateStore {
+	const statePath = getCredentialAutoImportStatePath(agentDir);
+	const lock = dependencies.withFileLock ?? withFileLock;
+	const rename = dependencies.rename ?? fs.rename;
+	return {
+		read: () => readCredentialAutoImportStateAtPath(statePath),
+		write: async mutation => {
+			if (
+				(mutation.lastImportVersion !== undefined && !isValidVersionMarker(mutation.lastImportVersion)) ||
+				(mutation.initialImportResolution !== undefined &&
+					!isInitialImportResolution(mutation.initialImportResolution))
+			) {
+				return false;
+			}
+			try {
+				await fs.mkdir(path.dirname(statePath), { recursive: true, mode: 0o700 });
+				await lock(statePath, async () => {
+					const current = await readCredentialAutoImportStateAtPath(statePath);
+					if (current.unreadable) throw new Error("Credential auto-import state became unreadable");
+					const next: CredentialAutoImportStateFile = { ...current.state };
+					if (mutation.lastImportVersion !== undefined) next.lastImportVersion = mutation.lastImportVersion;
+					if (next.initialImportResolution === undefined && mutation.initialImportResolution !== undefined) {
+						next.initialImportResolution = mutation.initialImportResolution;
+					}
+					await writeCredentialAutoImportStateAtomic(statePath, next, rename);
+				});
+				return true;
+			} catch {
+				logger.warn("Credential auto-import state persistence failed", { classification: "state-write-failed" });
+				return false;
+			}
+		},
+	};
+}
+
+export async function readCredentialAutoImportState(agentDir?: string): Promise<CredentialAutoImportStateReadResult> {
+	return createCredentialAutoImportStateStore(agentDir).read();
+}
+
+export function isCredentialAutoImportStateResolvedForVersion(
+	state: CredentialAutoImportStateFile,
+	version: string,
+): boolean {
+	return (
+		state.initialImportResolution === "declined" ||
+		(state.initialImportResolution === "accepted" && state.lastImportVersion === undefined) ||
+		(state.lastImportVersion !== undefined && state.lastImportVersion === version)
+	);
+}
+
+export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+	return (await readCredentialAutoImportState(agentDir)).state.lastImportVersion;
+}
+
+export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+	return createCredentialAutoImportStateStore(agentDir).write({ lastImportVersion: version });
+}
+
 export enum CredentialAutoImportFailureClass {
 	DiscoveryUnavailable = "discovery-unavailable",
 	SourceUnreadable = "source-unreadable",
@@ -93,6 +259,63 @@ export interface CredentialAutoImportResult {
 	globalDiscoveryFailure?: CredentialAutoImportFailure;
 }
 
+const CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS: readonly ExternalProvider[] = ["anthropic", "openai-codex"];
+const CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS: readonly CredentialOrigin[] = [
+	"claude-code-file",
+	"claude-code-keychain",
+	"codex-file",
+];
+const CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS: Record<CredentialOrigin, string> = {
+	"claude-code-file": "Claude Code file",
+	"claude-code-keychain": "Claude Code Keychain",
+	"codex-file": "Codex CLI file",
+};
+const CREDENTIAL_AUTO_IMPORT_FAILURE_CLASSES = new Set(Object.values(CredentialAutoImportFailureClass));
+
+export function formatCredentialAutoImportCandidateLabel(
+	candidate: Pick<ImportableCredential, "provider" | "origin">,
+): string {
+	const provider = CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS.includes(candidate.provider)
+		? EXTERNAL_PROVIDER_LABELS[candidate.provider]
+		: undefined;
+	const origin = CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS.includes(candidate.origin)
+		? CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS[candidate.origin]
+		: undefined;
+	return provider && origin ? `${provider} · ${origin}` : "External OAuth credential";
+}
+
+export function formatCredentialAutoImportPrompt(
+	candidates: readonly Pick<ImportableCredential, "provider" | "origin">[],
+): string {
+	const lines: string[] = [];
+	for (const provider of CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS) {
+		for (const origin of CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS) {
+			const count = candidates.filter(
+				candidate => candidate.provider === provider && candidate.origin === origin,
+			).length;
+			if (count > 0)
+				lines.push(
+					`${EXTERNAL_PROVIDER_LABELS[provider]} · ${CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS[origin]}: ${count}`,
+				);
+		}
+	}
+	return `External OAuth credentials found: ${candidates.length}\n${lines.join("\n")}`;
+}
+
+export function logCredentialAutoImportFailures(
+	trigger: CredentialAutoImportTrigger,
+	failures: readonly Pick<CredentialAutoImportFailure, "failureClass">[],
+): void {
+	const failureCounts: Partial<Record<CredentialAutoImportFailureClass, number>> = {};
+	for (const failure of failures) {
+		if (!CREDENTIAL_AUTO_IMPORT_FAILURE_CLASSES.has(failure.failureClass)) continue;
+		failureCounts[failure.failureClass] = (failureCounts[failure.failureClass] ?? 0) + 1;
+	}
+	if (Object.keys(failureCounts).length > 0) {
+		logger.warn("Credential auto-import completed with failures", { trigger, failureCounts });
+	}
+}
+
 export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
 
 export interface CredentialAutoImportOptions {
@@ -204,18 +427,38 @@ export function formatCredentialAutoImportResult(result: CredentialAutoImportRes
 	return lines;
 }
 
-export interface CredentialImportMarkerStore {
-	read: () => Promise<string | undefined> | string | undefined;
-	write: (version: string) => Promise<boolean> | boolean;
-}
-
 export interface StartupCredentialAutoImportOptions {
 	authStorage: CredentialAutoImportOptions["authStorage"];
 	modelRegistry: Pick<ModelRegistry, "refresh">;
 	discover?: CredentialAutoImportOptions["discover"];
 	version?: string;
 	agentDir?: string;
-	markerStore?: CredentialImportMarkerStore;
+	stateStore?: CredentialAutoImportStateStore;
+}
+
+function appendNoticeLine(notice: string | undefined, line: string): string {
+	return notice ? `${notice}\n${line}` : line;
+}
+
+async function readStateSafely(store: CredentialAutoImportStateStore): Promise<CredentialAutoImportStateReadResult> {
+	try {
+		return await store.read();
+	} catch {
+		logger.warn("Credential auto-import state read failed", { classification: "state-read-failed" });
+		return { state: {}, problems: [], unreadable: true };
+	}
+}
+
+async function writeStateSafely(
+	store: CredentialAutoImportStateStore,
+	mutation: CredentialAutoImportStateMutation,
+): Promise<boolean> {
+	try {
+		return await store.write(mutation);
+	} catch {
+		logger.warn("Credential auto-import state persistence failed", { classification: "state-write-failed" });
+		return false;
+	}
 }
 
 export async function runStartupCredentialAutoImportIfNeeded({
@@ -224,17 +467,15 @@ export async function runStartupCredentialAutoImportIfNeeded({
 	discover,
 	version = VERSION,
 	agentDir,
-	markerStore,
+	stateStore,
 }: StartupCredentialAutoImportOptions): Promise<string | undefined> {
-	const store = markerStore ?? {
-		read: () => readCredentialImportMarker(agentDir),
-		write: (nextVersion: string) => writeCredentialImportMarker(nextVersion, agentDir),
-	};
-	const lastVersion = await store.read();
-	if (lastVersion === version) {
-		// Steady state: user already completed this version's auto-import gate. Skip all file/Keychain reads.
+	const store = stateStore ?? createCredentialAutoImportStateStore(agentDir);
+	const stateRead = await readStateSafely(store);
+	if (stateRead.unreadable) {
+		logger.warn("Credential auto-import state unavailable", { classification: "state-unreadable" });
 		return undefined;
 	}
+	if (isCredentialAutoImportStateResolvedForVersion(stateRead.state, version)) return undefined;
 
 	const result = await runExternalCredentialAutoImport({
 		authStorage: activeAuthStorage,
@@ -242,17 +483,32 @@ export async function runStartupCredentialAutoImportIfNeeded({
 		trigger: "startup",
 	});
 	if (!result.discovered) {
+		logCredentialAutoImportFailures("startup", result.failures);
 		return undefined;
 	}
 
 	const candidates = filterAutoImportOAuthCredentials(result.discovery?.importable ?? []);
-	if (candidates.length > 0 && result.imported.length === 0 && result.skipped.length === 0) {
-		return undefined;
+	const handledCandidates = result.imported.length + result.skipped.length > 0;
+	if (result.failures.length > 0) logCredentialAutoImportFailures("startup", result.failures);
+	let persisted = true;
+	if (handledCandidates) {
+		persisted = await writeStateSafely(store, {
+			lastImportVersion: version,
+			initialImportResolution: "accepted",
+		});
+	} else if (candidates.length === 0 && result.failures.length === 0) {
+		persisted = await writeStateSafely(store, { lastImportVersion: version });
 	}
-	await store.write(version);
 
+	let notice = buildCredentialAutoImportNotice(result);
+	if (!persisted) notice = appendNoticeLine(notice, CREDENTIAL_AUTO_IMPORT_PERSISTENCE_WARNING);
 	if (result.imported.length > 0) {
-		await activeModelRegistry.refresh("offline");
+		try {
+			await activeModelRegistry.refresh("offline");
+		} catch {
+			logger.warn("Credential auto-import refresh failed", { classification: "refresh-failed" });
+			notice = appendNoticeLine(notice, CREDENTIAL_AUTO_IMPORT_REFRESH_WARNING);
+		}
 	}
-	return buildCredentialAutoImportNotice(result);
+	return notice;
 }

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -11,9 +11,9 @@ These instructions teach a Hermes-style coordinator how to operate SKC through t
 3. Store the returned `turn_id`.
 4. Prefer `{{TOOL_PREFIX}}_watch_events` with the stored `latest_seq` for event-driven progress; fall back to `{{TOOL_PREFIX}}_read_turn` or `{{TOOL_PREFIX}}_await_turn` for a specific `turn_id` until terminal.
    If a second task is needed while one turn is active, pass `queue: true`; the next queued turn is promoted after the active turn is reported terminal.
-5. If SKC asks a structured question, use `{{TOOL_PREFIX}}_list_questions` and answer with `{{TOOL_PREFIX}}_submit_question_answer`.
+5. If SKC asks structured questions, call `{{TOOL_PREFIX}}_list_questions` with `session_id`. It reconciles pending `workflow.gates.list` rows and returns bounded public questions, diagnostics, and reconciliation; `pending` is the current filter and `open` is a compatibility alias. Handle every pending row. Submit its `session_id`, `turn_id`, `question_id`, and `answer_binding` to `{{TOOL_PREFIX}}_submit_question_answer` with the advertised `answer`, a unique `idempotency_key`, and `allow_mutation: true`. That tool resolves through `workflow.gate_answer`, never generic `ask.answer`; re-list after restart, incomplete reconciliation is `terminal_uncertain`, stale/terminal rows are not answerable, identical replay is safe, and conflicting idempotency-key reuse fails. Never expect private gate payloads or raw values. This coordinator loop is separate from #2549/#2551 and unattended plain-CLI behavior.
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
-7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
+7. Use `{{TOOL_PREFIX}}_read_tail` only to inspect the latest assistant response through the SDK when structured turn state is insufficient; it never reads terminal output.
 
 ## Prefer high-level delegation
 
@@ -39,11 +39,9 @@ The Hermes bridge does not choose a model/provider. Generated setup configures `
 
 Provider-specific commands are examples only, never product defaults.
 
-## Visible routed-session fallback
+## Human-visible TUI boundary
 
-If a Hermes/OpenClaw/Clawhip-style operator needs a human-visible, channel-routed SKC pane instead of a pure Coordinator MCP session, use the visible session pattern in [`docs/skc-session-clawhip-routing.md`](../../../../../../docs/skc-session-clawhip-routing.md).
-
-Use that pattern only when the router must watch tmux output, send stale-session alerts, or inject follow-up prompts into the same visible pane. The short version is: prepare a dedicated worktree, register a stable tmux session through the host router, start interactive `skc`, wait for TUI readiness, inject the task prompt separately, and verify actual tool/work activity before reporting acceptance.
+A human may choose to run the local TUI in tmux for terminal visibility. That terminal is not a controller API: Hermes/OpenClaw/Clawhip-style operators must not inject prompts into, scrape, or route machine decisions through a tmux pane. Use the Coordinator MCP tools above for every external control and viewing operation.
 
 Do not put private channel ids, mention targets, socket names, tokens, or local routing policy into portable setup output. Keep those in the host/operator deployment.