@sayknow-cli/coding-agent 0.3.0 → 0.3.2

package/dist/types/tools/fetch.d.ts

@@ -1,8 +1,10 @@
 import type { AgentToolResult } from "@sayknow-cli/agent-core";
 import { type Component } from "@sayknow-cli/tui";
+import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
+import type { RenderResult } from "../web/scrapers/types";
 import { type OutputMeta } from "./output-meta";
 export declare function isReadableUrlPath(value: string): boolean;
 export interface ParsedReadUrlTarget {
@@ -16,6 +18,27 @@ interface FetchImagePayload {
     data: string;
     mimeType: string;
 }
+type FetchRenderResult = RenderResult & {
+    image?: FetchImagePayload;
+};
+/**
+ * Opt-in insane-search fallback for blocked / degraded public URL reads.
+ *
+ * Returns a finalized `method: "insane"` result on success, or null (so the
+ * caller continues with its normal degraded behavior). Fail-closed: no note,
+ * guard DNS, dependency probe, or subprocess when raw mode or the opt-in
+ * setting is off. The public-URL guard runs BEFORE any probe/spawn.
+ */
+export declare function tryInsaneFallback(args: {
+    url: string;
+    finalUrl: string;
+    timeout: number;
+    raw: boolean;
+    settings: Settings;
+    signal: AbortSignal | undefined;
+    fetchedAt: string;
+    notes: string[];
+}): Promise<FetchRenderResult | null>;
 export interface ReadUrlToolDetails {
     kind: "url";
     url: string;

package/dist/types/tools/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTelemetryConfig, AgentTool } from "@sayknow-cli/agent-core";
-import type { Model, ToolChoice } from "@sayknow-cli/ai";
+import type { Model, ServiceTier, ToolChoice } from "@sayknow-cli/ai";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
@@ -55,6 +55,7 @@ export * from "./search-tool-bm25";
 export * from "./skill";
 export * from "./ssh";
 export * from "./subagent";
+export * from "./telegram-send";
 export * from "./todo-write";
 export * from "./vim";
 export * from "./write";
@@ -172,6 +173,8 @@ export interface ToolSession {
     agentOutputManager?: AgentOutputManager;
     /** Settings instance for passing to subagents */
     settings: Settings;
+    /** Live service-tier intent of the parent session, inherited by `inherit` subagents. */
+    serviceTier?: ServiceTier;
     /** Plan mode state (if active) */
     getPlanModeState?: () => PlanModeState | undefined;
     /** Goal mode state (if active or paused) */

package/dist/types/tools/telegram-send.d.ts

@@ -0,0 +1,32 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import { z } from "zod/v4";
+import type { ToolSession } from "./index";
+declare const telegramSendSchema: z.ZodObject<{
+    path: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TelegramSendParams = z.infer<typeof telegramSendSchema>;
+interface TelegramSendDetails {
+    path: string;
+    caption?: string;
+    ok: boolean;
+    error?: string;
+}
+export declare class TelegramSendTool implements AgentTool<typeof telegramSendSchema, TelegramSendDetails> {
+    private readonly session;
+    readonly name = "telegram_send";
+    readonly label = "TelegramSend";
+    readonly summary = "Send a workspace file to Telegram";
+    readonly loadMode = "discoverable";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        path: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): TelegramSendTool | null;
+    private resolveContainedFile;
+    execute(_toolCallId: string, params: TelegramSendParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<TelegramSendDetails>, _context?: AgentToolContext): Promise<AgentToolResult<TelegramSendDetails>>;
+}
+export {};

package/dist/types/utils/changelog.d.ts

@@ -25,6 +25,7 @@ export declare function parseChangelog(changelogPath: string): Promise<Changelog
  * binary-identity changelog).
  */
 export declare function getDisplayChangelogEntries(): ChangelogEntry[];
+export declare function getInstalledVersionChangelogEntry(entries: readonly ChangelogEntry[], installedVersion: string): ChangelogEntry | undefined;
 /**
  * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
  */

package/dist/types/web/insane/bridge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Bridge from TypeScript to the vendored insane-search Python engine.
+ *
+ * Invokes `python3 -m engine "<url>" --json` per fallback attempt (cwd + PYTHONPATH
+ * pointed at the vendored engine), validates the JSON envelope, and maps it onto a
+ * discriminated result. Hardened: clamped timeout, AbortSignal propagation that
+ * kills+reaps the child, bounded stdout/stderr capture, and a per-process
+ * concurrency cap so blocked reads cannot fork-storm.
+ *
+ * Fail-closed: missing dependencies / bad output / auth-required never throw past
+ * the caller and never auto-install anything; they return ok:false with a stable,
+ * bounded note so `read` can continue with its normal degraded result.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+/** packages/coding-agent/vendor/insane-search */
+export declare const INSANE_VENDOR_DIR: string;
+/** Stable note prefixes — tests assert on these without depending on full stderr. */
+export declare const INSANE_NOTES: {
+    readonly guardBlocked: (reason: string) => string;
+    readonly vendorMissing: `insane fallback unavailable: vendor engine missing at packages/coding-agent/vendor/insane-search`;
+    readonly noPython: `insane fallback unavailable: python3 not found; install python3 and curl_cffi, then retry with web.insaneFallback=true`;
+    readonly noCurlCffi: `insane fallback unavailable: python3 cannot import curl_cffi; install curl_cffi for Phase 0-2`;
+    readonly noBrowser: `insane fallback unavailable: node/playwright/stealth dependencies missing for Phase 3; install dependencies under packages/coding-agent/vendor/insane-search/engine/templates`;
+    readonly timeout: (seconds: number) => string;
+    readonly invalidJson: `insane fallback failed: engine returned invalid JSON`;
+    readonly authRequired: `insane fallback stopped: authentication required`;
+    readonly verdict: (verdict: string) => string;
+    readonly untried: (routes: string) => string;
+    readonly mustBrowserMcp: `insane fallback requires browser MCP/manual phase: must_invoke_playwright_mcp=true`;
+    readonly concurrency: `insane fallback skipped: max concurrent engine attempts reached`;
+    readonly emptyContent: `insane fallback failed: engine reported ok but returned no content`;
+};
+/** Raw JSON envelope produced by `python3 -m engine --json`. */
+export interface InsaneFetchResultRaw {
+    ok?: boolean;
+    verdict?: string;
+    content?: string;
+    profile_used?: string;
+    trace?: unknown;
+    untried_routes?: string[];
+    must_invoke_playwright_mcp?: boolean;
+}
+export interface InsaneSuccess {
+    ok: true;
+    content: string;
+    profileUsed?: string;
+    notes: string[];
+}
+export interface InsaneFailure {
+    ok: false;
+    reason: string;
+    verdict?: string;
+    notes: string[];
+}
+export type InsaneBridgeResult = InsaneSuccess | InsaneFailure;
+export interface EngineInvocation {
+    url: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+export interface EngineRawOutput {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    aborted: boolean;
+}
+/** Seam: run the engine subprocess. Default spawns python3. */
+export type EngineRunner = (inv: EngineInvocation) => Promise<EngineRawOutput>;
+export interface InsaneDependencyStatus {
+    vendorPresent: boolean;
+    python: boolean;
+    curlCffi: boolean;
+    browser: boolean;
+}
+/** Seam: probe dependencies. Default probes the real environment (cached). */
+export type DependencyProber = () => Promise<InsaneDependencyStatus>;
+type SpawnImpl = typeof nodeSpawn;
+/** Real engine runner: `python3 -m engine "<url>" --json`. */
+export declare function runEngineSubprocess(inv: EngineInvocation, options?: {
+    spawnImpl?: SpawnImpl;
+}): Promise<EngineRawOutput>;
+/** Reset the probe cache between tests so probe state never leaks. */
+export declare function resetInsaneProbeCacheForTest(): void;
+/** Probe (and cache) the insane-search runtime dependencies. */
+export declare function probeInsaneDependencies(): Promise<InsaneDependencyStatus>;
+export declare function resetInsaneConcurrencyForTest(): void;
+export interface TryInsaneFetchOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    concurrencyLimit?: number;
+    /** Seam: dependency prober (default real, cached). */
+    prober?: DependencyProber;
+    /** Seam: engine runner (default real subprocess). */
+    runner?: EngineRunner;
+}
+/**
+ * Attempt to read `url` through the insane-search engine. The caller is
+ * responsible for the opt-in gate, raw-mode skip, and the public-URL guard
+ * (which MUST run before this is called). Never throws; always returns a result.
+ */
+export declare function tryInsaneFetch(url: string, options?: TryInsaneFetchOptions): Promise<InsaneBridgeResult>;
+export {};

package/dist/types/web/insane/url-guard.d.ts

@@ -0,0 +1,25 @@
+export interface PublicUrlAccepted {
+    ok: true;
+    url: URL;
+    addresses: string[];
+}
+export interface PublicUrlRejected {
+    ok: false;
+    reason: string;
+}
+export type PublicUrlResult = PublicUrlAccepted | PublicUrlRejected;
+/** Resolver seam so tests can inject DNS results without real lookups. */
+export type AddressResolver = (hostname: string) => Promise<string[]>;
+/** True for any address that is not a routable public unicast address. */
+export declare function isPrivateOrSpecialAddress(address: string): boolean;
+/**
+ * Validate that `rawUrl` is a public http/https target. Resolves DNS names and
+ * rejects any that map to a private/special address. Never throws; returns a
+ * discriminated result.
+ */
+export declare function validatePublicHttpUrl(rawUrl: string, options?: {
+    resolver?: AddressResolver;
+}): Promise<PublicUrlResult>;
+export declare function validatePublicHttpUrlForInsane(rawUrl: string, options?: {
+    resolver?: AddressResolver;
+}): Promise<PublicUrlResult>;

package/dist/types/web/scrapers/types.d.ts

@@ -1,4 +1,5 @@
 import type { AgentStorage } from "../../session/agent-storage";
+import type { AddressResolver } from "../insane/url-guard";
 export { formatNumber } from "@sayknow-cli/utils";
 export interface RenderResult {
     url: string;
@@ -27,6 +28,9 @@ export interface LoadPageOptions {
     body?: string;
     maxBytes?: number;
     signal?: AbortSignal;
+    publicUrlGuard?: boolean;
+    resolver?: AddressResolver;
+    maxRedirects?: number;
 }
 export interface LoadPageResult {
     content: string;
@@ -34,6 +38,7 @@ export interface LoadPageResult {
     finalUrl: string;
     ok: boolean;
     status?: number;
+    error?: string;
 }
 /**
  * Fetch a page with timeout and size limit

package/dist/types/web/scrapers/utils.d.ts

@@ -1,5 +1,6 @@
 import { isRecord } from "@sayknow-cli/utils";
 export { isRecord };
+import type { AddressResolver } from "../insane/url-guard";
 export declare function asRecord(value: unknown): Record<string, unknown> | null;
 export declare function asString(value: unknown): string | null;
 export declare function asNumber(value: unknown): number | null;
@@ -12,10 +13,15 @@ export type BinaryFetchResult = BinaryFetchSuccess | {
     ok: false;
     error?: string;
 };
+export interface FetchBinaryOptions {
+    publicUrlGuard?: boolean;
+    resolver?: AddressResolver;
+    maxRedirects?: number;
+}
 /**
  * Fetch binary content from a URL
  */
-export declare function fetchBinary(url: string, timeout?: number, signal?: AbortSignal): Promise<BinaryFetchResult>;
+export declare function fetchBinary(url: string, timeout?: number, signal?: AbortSignal, options?: FetchBinaryOptions): Promise<BinaryFetchResult>;
 /**
  * Convert binary content to markdown using markit.
  */

package/dist/types/web/search/provider.d.ts

@@ -20,5 +20,22 @@ export declare function looksHostedModelId(modelId: string | undefined): boolean
 export declare function isLocalBaseUrl(baseUrl: string | undefined): boolean;
 export declare function inferNativeProviderFromModel(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
 export declare function canUseGenericCredentials(authStorage: AuthStorage, ctx: ActiveSearchModelContext | undefined, sessionId?: string, signal?: AbortSignal): Promise<boolean>;
-export declare function shouldTryGenericOpenAICompat(authStorage: AuthStorage, ctx: ActiveSearchModelContext | undefined, sessionId?: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Native web-search provider to attempt by reusing the ACTIVE model's own
+ * credentials + baseUrl, dispatched by the model's wire protocol.
+ *
+ * This is the "native search over a proxy" path: when a model is served through
+ * a proxy/custom endpoint, its canonical search credentials (e.g. a dedicated
+ * `anthropic` key, or ChatGPT OAuth for `codex`) are usually absent, but the
+ * credential that authenticates the model itself — stored under the active
+ * provider id and aimed at `ctx.baseUrl` — can drive native web search just as
+ * well. Each provider's `search()` falls back to those active credentials when
+ * its canonical ones are missing.
+ *
+ * Returned ids are matched purely from the wire `api` (+ model-id family where a
+ * native tool only makes sense for that family); the providers themselves fail
+ * closed (and the chain falls through to DuckDuckGo) if the endpoint does not
+ * actually support web search.
+ */
+export declare function activeContextNativeId(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined;
 export declare function resolveProviderChain(options: ResolveProviderChainOptions): Promise<SearchProvider[]>;

package/dist/types/web/search/providers/insane.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Insane Search Provider
+ *
+ * Native TypeScript, fail-closed adaptation of the MIT-licensed upstream
+ * fivetaku/insane-search public-route strategy. This ports only safe Phase 0
+ * concepts: deterministic no-auth public endpoints plus route-attempt tracing.
+ *
+ * Deliberately excluded from upstream: TLS impersonation, browser/cookie warming,
+ * CAPTCHA/paywall/login bypasses, credential storage, Playwright automation, and
+ * auto dependency installation. Unsupported or terminal auth/paywall/block states
+ * throw instead of pretending a shallow fetch succeeded.
+ */
+import type { AuthStorage } from "@sayknow-cli/ai";
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+export interface InsaneRouteAttempt {
+    platform: InsanePlatform;
+    route: string;
+    ok: boolean;
+    status: number;
+    bytes: number;
+    note?: string;
+}
+type InsanePlatform = "reddit" | "x" | "youtube" | "hackernews";
+interface RouteSuccess {
+    platform: InsanePlatform;
+    route: string;
+    finalUrl: string;
+    sources: SearchSource[];
+    attempts: InsaneRouteAttempt[];
+}
+interface RouteFailure {
+    platform: InsanePlatform;
+    attempts: InsaneRouteAttempt[];
+}
+type RouteResult = RouteSuccess | RouteFailure | null;
+export declare function routeInsanePublicUrl(rawUrl: string, signal?: AbortSignal): Promise<RouteResult>;
+/** Execute safe Insane Search public-route discovery. */
+export declare function searchInsane(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Keyless provider that ports safe upstream public-route fallbacks only. */
+export declare class InsaneProvider extends SearchProvider {
+    readonly id = "insane";
+    readonly label = "Insane";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/providers/text-citations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Inline citation extraction shared by native web-search providers.
+ *
+ * Web-search-capable models sometimes return a genuinely grounded answer whose
+ * sources are written inline (markdown links or bare URLs) instead of as
+ * structured citation annotations. When a provider has independent proof that a
+ * web search actually ran, these helpers recover sources from the answer text so
+ * the result is not discarded.
+ */
+import type { SearchSource } from "../types";
+/** Append a source, de-duplicating by URL. */
+export declare function addSource(sources: SearchSource[], source: SearchSource): void;
+/**
+ * Strips prose punctuation and unmatched closing delimiters from extracted URLs.
+ * Models often return links embedded in markdown or sentence text.
+ */
+export declare function normalizeExtractedUrl(candidate: string): string | null;
+/**
+ * Extracts citation sources from markdown links and bare URLs in answer text.
+ * Used only as a fallback when a provider confirms a search ran but omits
+ * structured citation annotations.
+ */
+export declare function extractTextSources(text: string): SearchSource[];

package/dist/types/web/search/types.d.ts

@@ -4,7 +4,7 @@
  * Unified types for web search responses across supported providers.
  */
 /** Supported web search providers */
-export type SearchProviderId = "duckduckgo" | "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "xai" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng" | "openai-compatible";
+export type SearchProviderId = "duckduckgo" | "insane" | "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "xai" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng" | "openai-compatible";
 export type WebSearchMode = "on" | "off" | "auto";
 export interface ActiveSearchModelContext {
     provider: string;
@@ -15,7 +15,7 @@ export interface ActiveSearchModelContext {
     headers?: Record<string, string>;
     webSearch?: WebSearchMode;
 }
-export declare const CONFIGURABLE_SEARCH_PROVIDER_IDS: readonly ["duckduckgo", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
+export declare const CONFIGURABLE_SEARCH_PROVIDER_IDS: readonly ["duckduckgo", "insane", "exa", "brave", "jina", "kimi", "zai", "anthropic", "perplexity", "gemini", "codex", "xai", "tavily", "parallel", "kagi", "synthetic", "searxng"];
 export declare function isSearchProviderId(value: string): value is SearchProviderId;
 export declare function isConfigurableSearchProviderId(value: string): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number];
 export declare function isSearchProviderPreference(value: string): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number] | "auto";
@@ -96,6 +96,14 @@ export interface AnthropicCitation {
     cited_text: string;
     encrypted_index: string;
 }
+/**
+ * Error payload returned in `web_search_tool_result.content` when a server-side
+ * web search fails. Unlike the success case, this is an object, not an array.
+ */
+export interface AnthropicWebSearchToolResultError {
+    type: "web_search_tool_result_error";
+    error_code?: string;
+}
 export interface AnthropicContentBlock {
     type: string;
     /** Text content (for type="text") */
@@ -108,8 +116,8 @@ export interface AnthropicContentBlock {
     input?: {
         query: string;
     };
-    /** Search results (for type="web_search_tool_result") */
-    content?: AnthropicSearchResult[];
+    /** Search results array on success, or an error object on failure (type="web_search_tool_result") */
+    content?: AnthropicSearchResult[] | AnthropicWebSearchToolResultError;
 }
 export interface AnthropicApiResponse {
     id: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -28,7 +28,7 @@
 	"main": "./src/index.ts",
 	"types": "./dist/types/index.d.ts",
 	"bin": {
-		"skc": "src/cli.ts"
+		"skc": "bin/skc.js"
 	},
 	"scripts": {
 		"build": "bun scripts/build-binary.ts",
@@ -45,18 +45,19 @@
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
 		"prepack": "bun scripts/generate-docs-index.ts",
 		"generate-template": "bun scripts/generate-template.ts",
-		"install:defaults": "bun src/cli.ts setup defaults"
+		"install:defaults": "bun src/cli.ts setup defaults",
+		"verify:insane-vendor": "bun scripts/verify-insane-vendor.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.3.0",
-		"@sayknow-cli/agent-core": "0.3.0",
-		"@sayknow-cli/ai": "0.3.0",
-		"@sayknow-cli/natives": "0.3.0",
-		"@sayknow-cli/tui": "0.3.0",
-		"@sayknow-cli/utils": "0.3.0",
+		"@sayknow-cli/stats": "0.3.2",
+		"@sayknow-cli/agent-core": "0.3.2",
+		"@sayknow-cli/ai": "0.3.2",
+		"@sayknow-cli/natives": "0.3.2",
+		"@sayknow-cli/tui": "0.3.2",
+		"@sayknow-cli/utils": "0.3.2",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -73,17 +74,20 @@
 		"zod": "4.4.3"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.14"
+		"@types/bun": "^1.3.14",
+		"@types/ws": "^8.5.13"
 	},
 	"engines": {
 		"bun": ">=1.3.14"
 	},
 	"files": [
 		"src",
+		"bin",
 		"scripts",
 		"examples",
 		"README.md",
 		"CHANGELOG.md",
+		"vendor",
 		"dist/types"
 	],
 	"exports": {

package/scripts/g004-tmux-smoke.ts

@@ -0,0 +1,100 @@
+// G004 real-tmux smoke: exercises forceCloseSkcTmuxSession against LIVE tmux
+// sessions (tmux 3.6a). Proves the wrapper hard-kills SKC-managed live panes
+// (where remove refuses), refuses non-SKC sessions, and enforces session-id
+// matching. Produces durable evidence; not part of the unit suite.
+import assert from "node:assert";
+
+import {
+	buildSkcTmuxExactOptionTarget,
+	buildSkcTmuxProfileCommands,
+	resolveSkcTmuxCommand,
+} from "../src/skc-runtime/tmux-common";
+import { forceCloseSkcTmuxSession, removeSkcTmuxSession, statusSkcTmuxSession } from "../src/skc-runtime/tmux-sessions";
+
+const tmux = resolveSkcTmuxCommand(process.env);
+
+function sh(args: string[]): { code: number; err: string } {
+	const r = Bun.spawnSync([tmux, ...args], { stdout: "pipe", stderr: "pipe" });
+	return { code: r.exitCode, err: r.stderr.toString().trim() };
+}
+
+function makeRawSession(name: string): void {
+	const r = sh(["new-session", "-d", "-s", name, "sleep 600"]);
+	if (r.code !== 0) throw new Error(`failed to create tmux session ${name}: ${r.err}`);
+}
+
+function tagAsSkc(name: string, sessionId?: string): void {
+	const target = buildSkcTmuxExactOptionTarget(name);
+	for (const cmd of buildSkcTmuxProfileCommands(target, process.env, { sessionId })) {
+		const r = sh(cmd.args);
+		if (r.code !== 0) throw new Error(`failed to tag ${name} (${cmd.description}): ${r.err}`);
+	}
+}
+
+function exists(name: string): boolean {
+	return sh(["has-session", "-t", `=${name}`]).code === 0;
+}
+
+function killQuiet(name: string): void {
+	sh(["kill-session", "-t", `=${name}`]);
+}
+
+const suffix = `${process.pid}-${Date.now()}`;
+const live = `skc_g004live_${suffix}`;
+const raw = `g004raw_${suffix}`;
+const mism = `skc_g004mism_${suffix}`;
+const cleanup: string[] = [live, raw, mism];
+
+try {
+	// 1. SKC-managed LIVE session: remove refuses, force-close hard-kills.
+	makeRawSession(live);
+	tagAsSkc(live, "sess-g004");
+	const status = statusSkcTmuxSession(live);
+	assert.equal(status.profile, "1", "session must be recognized as SKC-managed");
+	assert.ok(status.panePids.length > 0, "session must have a live pane (sleep)");
+	console.log(`[g004] live SKC session up: ${live} panePids=${status.panePids.length}`);
+
+	let removeRefused = false;
+	try {
+		removeSkcTmuxSession(live);
+	} catch (e) {
+		removeRefused = /skc_tmux_session_live/.test(String(e));
+	}
+	assert.ok(removeRefused, "removeSkcTmuxSession must REFUSE a live pane");
+	console.log("[g004] remove refused live session (expected)");
+
+	const closed = forceCloseSkcTmuxSession(live, process.env, "sess-g004");
+	assert.equal(closed.name, live);
+	assert.ok(!exists(live), "force-close must hard-kill the live SKC session");
+	console.log("[g004] force-close hard-killed the live SKC session (id-matched)");
+
+	// 2. Non-SKC (untagged) session: force-close must refuse.
+	makeRawSession(raw);
+	let notManaged = false;
+	try {
+		forceCloseSkcTmuxSession(raw, process.env);
+	} catch (e) {
+		notManaged = /skc_tmux_session_(not_managed|not_found)/.test(String(e));
+	}
+	assert.ok(notManaged, "force-close must refuse a non-SKC tmux session");
+	assert.ok(exists(raw), "non-SKC session must be left untouched");
+	killQuiet(raw);
+	console.log("[g004] force-close refused + preserved non-SKC session (expected)");
+
+	// 3. SKC session with a MISMATCHED expected session id: must refuse.
+	makeRawSession(mism);
+	tagAsSkc(mism, "sess-real");
+	let idMismatch = false;
+	try {
+		forceCloseSkcTmuxSession(mism, process.env, "sess-WRONG");
+	} catch (e) {
+		idMismatch = /skc_tmux_session_id_mismatch/.test(String(e));
+	}
+	assert.ok(idMismatch, "force-close must refuse on session-id mismatch");
+	assert.ok(exists(mism), "mismatched session must be left untouched");
+	console.log("[g004] force-close refused on session-id mismatch (expected)");
+
+	console.log("[g004] PASS: forceCloseSkcTmuxSession verified against live tmux");
+} finally {
+	for (const name of cleanup) killQuiet(name);
+}