@sayknow-cli/coding-agent 0.2.4 → 0.2.6

package/src/prompts/tools/search.md

@@ -21,5 +21,5 @@ Searches files using powerful regex matching.
 - You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
 - Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
 - If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
-- If the search is open-ended, requiring multiple rounds, you MUST use the Task tool with the explore subagent instead of chaining `search` calls yourself.
+- If the search is open-ended and requires multiple rounds across subsystems, delegate a bounded fact-finding task to an appropriate canonical role agent (`planner` for sequencing/context maps or `architect` for read-only architecture assessment) instead of chaining broad `search` calls yourself.
 </critical>

package/src/prompts/tools/task.md

@@ -28,13 +28,12 @@ Subagents have no conversation history. Every fact, file path, and direction the
 {{/if}}
 {{#if independentMode}}- `.inheritContext`: independent mode cannot inherit parent conversation. Omit it or set `"none"`; any non-`none` value is rejected before scheduling.{{/if}}
 {{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
-- `spawnPlan` (optional): required before any batch with more than 4 tasks, and before a reviewer agent spawns `explore`; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
+- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
 {{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
 </parameters>
 
 <rules>
 - HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.
-- Reviewer->explore gate: a `reviewer` spawning `explore` is rejected before launch unless `spawnPlan` is complete, even for a single task.
 - NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
 - **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
 {{#if ircEnabled}}

package/src/research-plan/index.ts

@@ -0,0 +1 @@
+export * from "./ledger";

package/src/research-plan/ledger.ts

@@ -0,0 +1,177 @@
+export type ResearchPlanConfidence = "low" | "medium" | "high";
+
+export type ResearchEvidenceVerdict = "support" | "contradict" | "uncertain";
+
+export interface ResearchPlanItem {
+	claim: string;
+	confidence: ResearchPlanConfidence;
+	unknowns: string[];
+	evidenceNeeded: string[];
+	counterexampleQueries: string[];
+	sourceConflictPolicy: string;
+	dropCondition: string;
+	verifierChecks: string[];
+}
+
+export interface ResearchEvidenceEntry {
+	claim: string;
+	source: string;
+	confidence: ResearchPlanConfidence;
+	verdict: ResearchEvidenceVerdict;
+	notes?: string;
+}
+
+export interface ResearchLedgerVerdict {
+	claim: string;
+	finalVerdict: "accepted" | "rejected" | "uncertain";
+	survivingSources: ResearchEvidenceEntry[];
+	rejectReason?: string;
+	unresolvedUnknowns: string[];
+}
+
+export interface ResearchPlanValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+const CONFIDENCE_VALUES = new Set<ResearchPlanConfidence>(["low", "medium", "high"]);
+const EVIDENCE_VERDICTS = new Set<ResearchEvidenceVerdict>(["support", "contradict", "uncertain"]);
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function validateStringArray(value: unknown, field: string, minLength = 1): string[] {
+	if (!Array.isArray(value)) return [`${field} must be an array`];
+	if (value.length < minLength) return [`${field} must contain at least ${minLength} item(s)`];
+	return value.flatMap((item, index) =>
+		isNonEmptyString(item) ? [] : [`${field}[${index}] must be a non-empty string`],
+	);
+}
+
+export function validateResearchPlanItem(item: Partial<ResearchPlanItem>): ResearchPlanValidationResult {
+	const errors: string[] = [];
+	if (!isNonEmptyString(item.claim)) errors.push("claim must be a non-empty string");
+	if (!item.confidence || !CONFIDENCE_VALUES.has(item.confidence)) {
+		errors.push("confidence must be one of: low, medium, high");
+	}
+	errors.push(...validateStringArray(item.unknowns, "unknowns", 0));
+	errors.push(...validateStringArray(item.evidenceNeeded, "evidenceNeeded"));
+	errors.push(...validateStringArray(item.counterexampleQueries, "counterexampleQueries"));
+	if (!isNonEmptyString(item.sourceConflictPolicy)) errors.push("sourceConflictPolicy must be a non-empty string");
+	if (!isNonEmptyString(item.dropCondition)) errors.push("dropCondition must be a non-empty string");
+	errors.push(...validateStringArray(item.verifierChecks, "verifierChecks"));
+	return { valid: errors.length === 0, errors };
+}
+
+export function validateResearchEvidenceEntry(entry: Partial<ResearchEvidenceEntry>): ResearchPlanValidationResult {
+	const errors: string[] = [];
+	if (!isNonEmptyString(entry.claim)) errors.push("claim must be a non-empty string");
+	if (!isNonEmptyString(entry.source)) errors.push("source must be a non-empty string");
+	if (!entry.confidence || !CONFIDENCE_VALUES.has(entry.confidence)) {
+		errors.push("confidence must be one of: low, medium, high");
+	}
+	if (!entry.verdict || !EVIDENCE_VERDICTS.has(entry.verdict)) {
+		errors.push("verdict must be one of: support, contradict, uncertain");
+	}
+	return { valid: errors.length === 0, errors };
+}
+
+function lower(value: string): string {
+	return value.toLowerCase();
+}
+
+function matchesDropCondition(item: ResearchPlanItem, evidence: ResearchEvidenceEntry[]): string | undefined {
+	const condition = lower(item.dropCondition);
+	const contradiction = evidence.find(entry => entry.verdict === "contradict");
+	if (contradiction && /(counterexample|contradict|conflict|falsif)/.test(condition)) {
+		return `dropCondition matched by contradictory source: ${contradiction.source}`;
+	}
+	const unresolved = evidence.find(entry => entry.verdict === "uncertain");
+	if (unresolved && /(unknown|unresolved|uncertain)/.test(condition)) {
+		return `dropCondition matched by unresolved evidence: ${unresolved.source}`;
+	}
+	return undefined;
+}
+
+function sourceConflictReason(item: ResearchPlanItem, evidence: ResearchEvidenceEntry[]): string | undefined {
+	const supporting = evidence.filter(entry => entry.verdict === "support");
+	const contradicting = evidence.filter(entry => entry.verdict === "contradict");
+	if (supporting.length === 0 || contradicting.length === 0) return undefined;
+	const policy = lower(item.sourceConflictPolicy);
+	if (/(reject|drop|do not accept|prefer contradiction|requires resolution)/.test(policy)) {
+		return `sourceConflictPolicy rejected mixed support/contradiction (${supporting.length} support, ${contradicting.length} contradict)`;
+	}
+	return "source conflict remains unresolved";
+}
+
+export function evaluateResearchLedger(
+	item: ResearchPlanItem,
+	evidence: readonly ResearchEvidenceEntry[],
+): ResearchLedgerVerdict {
+	const relevantEvidence = evidence.filter(entry => entry.claim === item.claim);
+	const invalidItem = validateResearchPlanItem(item);
+	if (!invalidItem.valid) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: [],
+			rejectReason: `invalid research plan item: ${invalidItem.errors.join("; ")}`,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const invalidEvidence = relevantEvidence.flatMap(entry => validateResearchEvidenceEntry(entry).errors);
+	if (invalidEvidence.length > 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: [],
+			rejectReason: `invalid evidence entry: ${invalidEvidence.join("; ")}`,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	if (relevantEvidence.length === 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "uncertain",
+			survivingSources: [],
+			rejectReason: "no evidence collected for claim",
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const supporting = relevantEvidence.filter(entry => entry.verdict === "support");
+	const firstContradiction = relevantEvidence.find(entry => entry.verdict === "contradict");
+	let dropReason = matchesDropCondition(item, relevantEvidence) ?? sourceConflictReason(item, relevantEvidence);
+	// A counterexample with no surviving support falsifies the claim regardless of how the
+	// dropCondition / sourceConflictPolicy prose is worded. Without this, a purely contradicted
+	// claim would slip through as "uncertain" and reopen the hallucination survival path the
+	// evidence ledger exists to close (a contested claim already rejects via sourceConflictReason).
+	if (!dropReason && firstContradiction && supporting.length === 0) {
+		dropReason = `claim contradicted by counterexample with no supporting evidence: ${firstContradiction.source}`;
+	}
+	if (dropReason) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: supporting,
+			rejectReason: dropReason,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const uncertain = relevantEvidence.some(entry => entry.verdict === "uncertain");
+	if (uncertain || supporting.length === 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "uncertain",
+			survivingSources: supporting,
+			rejectReason: uncertain ? "unresolved uncertainty remains" : "no supporting evidence survived verification",
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	return {
+		claim: item.claim,
+		finalVerdict: "accepted",
+		survivingSources: supporting,
+		unresolvedUnknowns: [],
+	};
+}

package/src/rlm/artifacts.ts

@@ -1,12 +1,17 @@
 /**
- * RLM session artifact layout under <cwd>/.skc/rlm/<sessionId>/.
+ * RLM session artifact layout under <cwd>/.skc/_session-{skcSessionId}/rlm/<rlmSessionId>/.
+ *
+ * The SKC session id (process boundary) scopes the directory; the RLM session id
+ * names the individual research run within it. The two ids are kept distinct.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { readNotebookDocument } from "../edit/notebook";
+import { rlmArtifactRoot } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForWrite } from "../skc-runtime/session-resolution";
 import type { RlmArtifactPaths } from "./types";
 
-export const RLM_DIR_SEGMENT = path.join(".skc", "rlm");
+export const RLM_DIR_SEGMENT = "rlm";
 
 const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
 
@@ -25,7 +30,11 @@ export function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArti
 	if (!isValidRlmSessionId(sessionId)) {
 		throw new Error(`Invalid RLM session id: ${JSON.stringify(sessionId)}`);
 	}
-	const dir = path.join(cwd, RLM_DIR_SEGMENT, sessionId);
+	const dir = rlmArtifactRoot(
+		cwd,
+		resolveSkcSessionForWrite(cwd, { envSessionId: process.env.SKC_SESSION_ID }).skcSessionId,
+		sessionId,
+	);
 	return {
 		dir,
 		notebookPath: path.join(dir, "notebook.ipynb"),

package/src/rlm/index.ts

@@ -15,6 +15,7 @@ import { type RlmPreset, runRootCommand } from "../main";
 import rlmReportCommandPrompt from "../prompts/system/rlm-report-command.md" with { type: "text" };
 import type { CreateAgentSessionOptions } from "../sdk";
 import type { AgentSession } from "../session/agent-session";
+import { resolveSessionIdFromSources, writeSessionActivityMarker } from "../skc-runtime/session-resolution";
 import {
 	ensureRlmSessionDir,
 	generateRlmSessionId,
@@ -231,6 +232,12 @@ async function writeRlmMetadata(input: {
 		successfulRuns: input.successfulRuns,
 	};
 	await Bun.write(input.paths.metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+	// Best-effort: update the per-session activity marker so latest-session auto-detect
+	// accounts for RLM-only generated output (AC2). Never let marker failure break RLM.
+	const skcSessionId = resolveSessionIdFromSources({ envSessionId: process.env.SKC_SESSION_ID })?.skcSessionId;
+	if (skcSessionId) {
+		await writeSessionActivityMarker(input.cwd, skcSessionId, { writer: "rlm" }).catch(() => {});
+	}
 }
 
 export async function runRlmCommand(argv: string[]): Promise<void> {

package/src/runtime-mcp/config-writer.ts

@@ -149,6 +149,52 @@ export async function updateMCPServer(filePath: string, name: string, config: MC
 	await writeMCPConfigFile(filePath, updated);
 }
 
+/**
+ * Result of an {@link upsertMCPServer} call.
+ * - `added`: server did not exist and was written.
+ * - `updated`: server existed and was overwritten because `force` was set.
+ * - `skipped`: server existed and `force` was not set, so nothing was written.
+ */
+export type UpsertMCPServerResult =
+	| { status: "added" }
+	| { status: "updated" }
+	| { status: "skipped"; reason: "exists" };
+
+/**
+ * Add an MCP server, or overwrite an existing one only when `force` is set.
+ *
+ * Collision-aware wrapper over {@link addMCPServer} / {@link updateMCPServer} used by
+ * `skc migrate`. Never connects to the server. Reuses the underlying writers so the
+ * rest of the config file (including `disabledServers`) is preserved on update.
+ *
+ * @throws Error if the server name or config is invalid (validated before any write).
+ */
+export async function upsertMCPServer(
+	filePath: string,
+	name: string,
+	config: MCPServerConfig,
+	options: { force?: boolean } = {},
+): Promise<UpsertMCPServerResult> {
+	// Validate name up front so an invalid name fails regardless of collision state.
+	const nameError = validateServerName(name);
+	if (nameError) {
+		throw new Error(nameError);
+	}
+
+	const existing = await getMCPServer(filePath, name);
+	if (existing) {
+		if (!options.force) {
+			return { status: "skipped", reason: "exists" };
+		}
+		// updateMCPServer preserves the rest of MCPConfigFile, incl. disabledServers.
+		await updateMCPServer(filePath, name, config);
+		return { status: "updated" };
+	}
+
+	await addMCPServer(filePath, name, config);
+	return { status: "added" };
+}
+
 /**
  * Remove an MCP server from a config file.
  *

package/src/session/agent-session.ts

@@ -44,7 +44,6 @@ import {
 	type EmergencyCompactionSample,
 	emergencyCompactionReason,
 	estimateMessageTokensHeuristic,
-	estimateTokens,
 	generateBranchSummary,
 	generateHandoff,
 	prepareCompaction,
@@ -217,6 +216,11 @@ import { MCPManager } from "../runtime-mcp/manager";
 import { deobfuscateSessionContext, type SecretObfuscator } from "../secrets/obfuscator";
 import { formatNoCredentialOnboardingError, formatNoModelOnboardingError } from "../setup/model-onboarding-guidance";
 import { buildSkcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../skc-runtime/goal-mode-request";
+import {
+	assertNonEmptySkcSessionId,
+	modeStatePath as sessionModeStatePath,
+	sessionStateDir,
+} from "../skc-runtime/session-layout";
 import { persistCoordinatorRuntimeStateFromEvent } from "../skc-runtime/session-state-sidecar";
 import { writeArtifact } from "../skc-runtime/state-writer";
 import { requestSkcWorkerIntegrationAttempt } from "../skc-runtime/team-runtime";
@@ -225,7 +229,7 @@ import {
 	readVisibleSkillActiveState,
 	syncSkillActiveState,
 } from "../skill-state/active-state";
-import { assertDeepInterviewMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
+import { assertWorkflowMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import {
@@ -313,13 +317,6 @@ export type AgentSessionEvent =
 	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
 	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
 
-/**
- * Safe path component pattern used to validate session-id segments before
- * joining them into `.skc/state` paths. Mirrors the regex used by the
- * `skc state` runtime selector resolver.
- */
-const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
-
 function isUnderProjectSkc(cwd: string, targetPath: string): boolean {
 	const relative = path.relative(path.join(path.resolve(cwd), ".skc"), path.resolve(targetPath));
 	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -1371,21 +1368,17 @@ export class AgentSession {
 	getActiveSkillPhase(): string | undefined {
 		const active = this.#activeSkillState;
 		if (!active) return undefined;
-		// Path safety: refuse to read mode-state files when the skill or
-		// session-id are not safe path components. The `skill` tool
-		// interprets undefined as a non-terminal phase, so chaining is
-		// refused — there is no risk of bypassing the guard via a custom
-		// skill name with `..` or a session-id with separators.
 		if (!isCanonicalSkcWorkflowSkill(active.skill)) return undefined;
-		if (active.sessionId !== undefined && !SAFE_PATH_COMPONENT.test(active.sessionId)) {
-			return undefined;
-		}
+		const sessionId = active.sessionId ?? this.sessionManager.getSessionId();
 		try {
-			const stateDir = path.join(this.sessionManager.getCwd(), ".skc", "state");
-			const segments = active.sessionId
-				? [stateDir, "sessions", encodeURIComponent(active.sessionId).replaceAll(".", "%2E")]
-				: [stateDir];
-			const filePath = path.join(...segments, `${active.skill}-state.json`);
+			assertNonEmptySkcSessionId(sessionId, "AgentSession.getActiveSkillPhase");
+			// Keep the session-state-dir construction explicit here so the chain guard
+			// refuses to fall back to a legacy root `.skc/state` read.
+			const stateDir = sessionStateDir(this.sessionManager.getCwd(), sessionId);
+			const filePath = path.join(
+				stateDir,
+				path.basename(sessionModeStatePath(this.sessionManager.getCwd(), sessionId, active.skill)),
+			);
 			const raw = fs.readFileSync(filePath, "utf-8");
 			const parsed = JSON.parse(raw) as { current_phase?: unknown };
 			return typeof parsed.current_phase === "string" ? parsed.current_phase : undefined;
@@ -1475,7 +1468,7 @@ export class AgentSession {
 			}
 			const sanitized = sanitizeMessage(providerMessages[i]!);
 			if (!sanitized) continue;
-			const messageTokens = estimateTokens(sanitized);
+			const messageTokens = estimateMessageTokensHeuristic(sanitized);
 			if (maxTokens > 0 && approximateTokens + messageTokens > maxTokens) {
 				recordSkip("token-limit");
 				continue;
@@ -3764,7 +3757,7 @@ export class AgentSession {
 	 * prompts or tool execution can run.
 	 */
 	#wrapToolForDeepInterviewMutationGuard<T extends AgentTool>(tool: T): T {
-		if (!["edit", "write", "ast_edit", "bash"].includes(tool.name)) return tool;
+		if (!["edit", "write", "ast_edit"].includes(tool.name)) return tool;
 		return new Proxy(tool, {
 			get: (target, prop) => {
 				if (prop !== "execute") return Reflect.get(target, prop, target);
@@ -3775,7 +3768,7 @@ export class AgentSession {
 					onUpdate: never,
 					ctx: never,
 				) => {
-					await assertDeepInterviewMutationAllowed({
+					await assertWorkflowMutationAllowed({
 						cwd: this.sessionManager.getCwd(),
 						sessionId: this.sessionManager.getSessionId(),
 						tool: target,
@@ -9901,9 +9894,9 @@ export class AgentSession {
 	#estimateContextTokensForCompaction(pendingMessages: readonly AgentMessage[]): {
 		tokens: number;
 	} {
-		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageNativeContextTokens(message));
+		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageCompactionDeltaTokens(message));
 		return {
-			tokens: estimate.tokens + this.#estimateMessagesNativeContextTokens(pendingMessages),
+			tokens: estimate.tokens + this.#estimateMessagesCompactionDeltaTokens(pendingMessages),
 		};
 	}
 
@@ -9949,10 +9942,10 @@ export class AgentSession {
 		};
 	}
 
-	#estimateMessagesNativeContextTokens(messages: readonly AgentMessage[]): number {
+	#estimateMessagesCompactionDeltaTokens(messages: readonly AgentMessage[]): number {
 		let tokens = 0;
 		for (const message of messages) {
-			tokens += this.#estimateMessageNativeContextTokens(message);
+			tokens += this.#estimateMessageCompactionDeltaTokens(message);
 		}
 		return tokens;
 	}
@@ -9965,11 +9958,17 @@ export class AgentSession {
 		return tokens;
 	}
 
-	#nativeTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
+	/**
+	 * Conservative inflation applied to the native-free chars/4 estimate of the
+	 * UNSENT context delta. chars/4 undercounts dense code/CJK, so we bias high
+	 * to compact slightly early rather than overflow the model window before the
+	 * next provider response re-anchors the exact count.
+	 */
+	#compactionDeltaInflation = 1.2;
+	#compactionDeltaTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
 
-	/** Cheap content-size signal to invalidate the native token cache on mutation (growth). */
 	/**
-	 * Cheap content-size signal to invalidate the native token cache on mutation. Recursively
+	 * Cheap content-size signal to invalidate the compaction-delta token cache on mutation. Recursively
 	 * sums string lengths across the whole message (depth-bounded), so it covers every
 	 * provider-visible shape (text/thinking/tool args, toolResult output, tool names, etc.)
 	 * without allocating a serialized copy. A size-preserving in-place edit yields only a
@@ -9992,19 +9991,22 @@ export class AgentSession {
 		return 0;
 	}
 
-	#estimateMessageNativeContextTokens(message: AgentMessage): number {
-		// F10/F22: cache the expensive native token count per message object, invalidated by a
-		// cheap content-size signal, so unchanged (stable-size) messages are not re-tokenized on
-		// every pre-prompt estimate. A rare size-preserving in-place edit yields only a benign
-		// token-estimate drift, never wrong output.
+	#estimateMessageCompactionDeltaTokens(message: AgentMessage): number {
+		// Provider usage anchors the already-sent context (see calculatePromptTokens); this
+		// estimates only the UNSENT delta with the native-free chars/4 heuristic, inflated by
+		// #compactionDeltaInflation so dense input cannot undercount us past the compaction
+		// threshold before the next provider response re-anchors the exact count. Cached per
+		// message object, invalidated by a cheap content-size signal; a rare size-preserving
+		// in-place edit yields only a benign estimate drift, never wrong output.
 		const len = this.#messageTokenSize(message);
-		const cached = this.#nativeTokenCache.get(message);
+		const cached = this.#compactionDeltaTokenCache.get(message);
 		if (cached && cached.len === len) return cached.tokens;
-		let tokens = 0;
+		let heuristic = 0;
 		for (const llmMessage of convertToLlm([message])) {
-			tokens += estimateTokens(llmMessage);
+			heuristic += estimateMessageTokensHeuristic(llmMessage);
 		}
-		this.#nativeTokenCache.set(message, { len, tokens });
+		const tokens = Math.ceil(heuristic * this.#compactionDeltaInflation);
+		this.#compactionDeltaTokenCache.set(message, { len, tokens });
 		return tokens;
 	}
 

package/src/session/session-manager.ts

@@ -1129,6 +1129,23 @@ function formatTimeAgo(date: Date): string {
 	return date.toLocaleDateString();
 }
 
+async function movePathAcrossDevicesSafe(source: string, destination: string): Promise<void> {
+	try {
+		await fs.promises.rename(source, destination);
+		return;
+	} catch (error) {
+		if (!hasFsCode(error, "EXDEV")) throw error;
+	}
+	const stat = await fs.promises.stat(source);
+	if (stat.isDirectory()) {
+		await fs.promises.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+		await fs.promises.rm(source, { recursive: true, force: false });
+		return;
+	}
+	await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_EXCL);
+	await fs.promises.unlink(source);
+}
+
 const MAX_PERSIST_CHARS = 500_000;
 const TRUNCATION_NOTICE = "\n\n[Session persistence truncated large content]";
 /** Minimum base64 length to externalize to blob store (skip tiny inline images) */
@@ -2498,14 +2515,14 @@ export class SessionManager {
 			try {
 				// Guard: session file may not exist yet (no assistant messages persisted)
 				if (hadSessionFile) {
-					await fs.promises.rename(oldSessionFile, newSessionFile);
+					await movePathAcrossDevicesSafe(oldSessionFile, newSessionFile);
 					movedSessionFile = true;
 				}
 
 				try {
 					const stat = await fs.promises.stat(oldArtifactDir);
 					if (stat.isDirectory()) {
-						await fs.promises.rename(oldArtifactDir, newArtifactDir);
+						await movePathAcrossDevicesSafe(oldArtifactDir, newArtifactDir);
 						movedArtifactDir = true;
 					}
 				} catch (err) {

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

@@ -29,6 +29,14 @@ 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
+
+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.
+
+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.
+
 ## Safety
 
 - Mutating tools require bridge startup mutation classes and per-call consent.

package/src/setup/hermes-setup.ts

@@ -404,7 +404,7 @@ async function installConfig(spec: CoordinatorSetupSpec, force: boolean): Promis
 
 async function runSmoke(spec: CoordinatorSetupSpec): Promise<HermesSetupResult["smoke"]> {
 	const requiredTools = [...COORDINATOR_MCP_TOOL_NAMES];
-	const server = createCoordinatorMcpServer({ env: {} });
+	const server = createCoordinatorMcpServer({ env: renderHermesServerBlock(spec).env as NodeJS.ProcessEnv });
 	const listed = await server.handleJsonRpc({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} });
 	const listedResult = isRecord(listed.result) ? listed.result : {};
 	const tools = Array.isArray(listedResult.tools) ? listedResult.tools : [];