@sayknow-cli/coding-agent 0.5.1 → 0.5.2

package/dist/types/skc-runtime/tmux-sessions.d.ts

@@ -1,4 +1,4 @@
-import { type OwnerIsolationProbeSync, type PlanResponse, type TmuxOwnerIsolationExecutionDependencies, type TmuxOwnerIsolationExecutionResult } from "./tmux-owner-isolation";
+import { type AbandonedIdentityCensus, type IdentityCreateKey, type IdentityCreateReservationResult, type OwnerIsolationProbeSync, type PlanResponse, type TmuxOwnerIsolationExecutionDependencies, type TmuxOwnerIsolationExecutionResult } from "./tmux-owner-isolation";
 export interface SkcTmuxSessionStatus {
     name: string;
     attached: boolean;
@@ -67,6 +67,17 @@ export interface ForceCloseOwnerDependencies {
 }
 export interface CreateSkcTmuxSessionOptions {
     platform?: NodeJS.Platform;
+    /**
+     * Restore only: run the child in the session's recorded directory instead of
+     * this process's cwd.
+     */
+    cwd?: string;
+    /**
+     * Restore only: argv appended to the `skc` child, e.g. `["--resume", "<id>"]`.
+     * Restore reuses this creator verbatim so it inherits the same identity fence
+     * and owner-isolation proof as an ordinary create.
+     */
+    childArgs?: string[];
 }
 export type CreateOwnerIsolationTestDependencies = {
     probe?: Partial<OwnerIsolationProbeSync>;
@@ -83,6 +94,20 @@ export declare function findSkcTmuxSessionByBranch(branch: string, env?: NodeJS.
 export declare function findSkcTmuxSessionByName(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
 export declare function findSkcTmuxSessionByScope(project: string, branch: string | null | undefined, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
 export declare function statusSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus;
+/**
+ * Live-tmux census for authority-first recovery of an abandoned reservation.
+ *
+ * Authority is the CURRENT published generation on disk compared against the
+ * live session's canonical tags — never the reservation's own `phase`, because a
+ * creator can publish and then die before recording that it published.
+ */
+/**
+ * Resolves a reservation refused because its previous owner died after reaching
+ * the helper. Shared by every producer so none of them can brick an identity by
+ * treating an abandoned row as a permanent collision.
+ */
+export declare function settleAbandonedIdentity(reserved: IdentityCreateReservationResult, identityKey: IdentityCreateKey, census: AbandonedIdentityCensus): IdentityCreateReservationResult;
+export declare function abandonedIdentityCensus(tmuxCommand: string, env: NodeJS.ProcessEnv, stateFile: string): AbandonedIdentityCensus;
 export declare function createSkcTmuxSession(env?: NodeJS.ProcessEnv, options?: CreateSkcTmuxSessionOptions): SkcTmuxSessionStatus;
 /** Proves a managed reusable name still resolves to one immutable session on one server. */
 export declare function proveSkcTmuxSessionMutationTarget(sessionName: string, env?: NodeJS.ProcessEnv): ProvenTmuxSessionIdentity;

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

@@ -29,13 +29,92 @@ export declare const askSchema: z.ZodObject<{
         }, z.core.$strip>>;
         multi: z.ZodOptional<z.ZodBoolean>;
         recommended: z.ZodOptional<z.ZodNumber>;
-        deepInterview: z.ZodOptional<z.ZodObject<{
+        workflowGate: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodEnum<{
+                "deep-interview": "deep-interview";
+                ralplan: "ralplan";
+                ultragoal: "ultragoal";
+            }>;
+            kind: z.ZodEnum<{
+                question: "question";
+                approval: "approval";
+                execution: "execution";
+            }>;
+        }, z.core.$strip>>;
+        deepInterview: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            round: z.ZodLiteral<0>;
+            component: z.ZodLiteral<"review-topology">;
+            intent_contract: z.ZodObject<{
+                items: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    category: z.ZodEnum<{
+                        surface: "surface";
+                        artifact: "artifact";
+                        integration: "integration";
+                        constraint: "constraint";
+                    }>;
+                    statement: z.ZodString;
+                }, z.core.$strict>>;
+                confirmation_options: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
             round_id: z.ZodOptional<z.ZodString>;
+            dimension: z.ZodString;
+            ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
             round: z.ZodNumber;
+            intent_review: z.ZodObject<{
+                observed_items: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    category: z.ZodEnum<{
+                        surface: "surface";
+                        artifact: "artifact";
+                        integration: "integration";
+                        constraint: "constraint";
+                    }>;
+                    statement: z.ZodString;
+                }, z.core.$strict>>;
+                supporting_substitutions: z.ZodArray<z.ZodObject<{
+                    removed_id: z.ZodString;
+                    replacement_ids: z.ZodArray<z.ZodString>;
+                    rationale: z.ZodString;
+                }, z.core.$strict>>;
+                approval_options: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            round_id: z.ZodOptional<z.ZodString>;
             component: z.ZodString;
             dimension: z.ZodString;
             ambiguity: z.ZodNumber;
-        }, z.core.$strip>>;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
+            round_id: z.ZodOptional<z.ZodString>;
+            round: z.ZodNumber;
+            component: z.ZodString;
+            dimension: z.ZodString;
+            ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>]>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AskToolInput = z.infer<typeof askSchema>;
@@ -54,6 +133,8 @@ export interface AskToolDetails {
     multi?: boolean;
     selectedOptions?: string[];
     customInput?: string;
+    /** Set when the user answered with a clarification question instead of a choice. */
+    clarificationQuestion?: string;
     /** Multi-part question mode */
     results?: QuestionResult[];
 }
@@ -80,13 +161,92 @@ export declare class AskTool implements AgentTool<typeof askSchema, AskToolDetai
             }, z.core.$strip>>;
             multi: z.ZodOptional<z.ZodBoolean>;
             recommended: z.ZodOptional<z.ZodNumber>;
-            deepInterview: z.ZodOptional<z.ZodObject<{
+            workflowGate: z.ZodOptional<z.ZodObject<{
+                stage: z.ZodEnum<{
+                    "deep-interview": "deep-interview";
+                    ralplan: "ralplan";
+                    ultragoal: "ultragoal";
+                }>;
+                kind: z.ZodEnum<{
+                    question: "question";
+                    approval: "approval";
+                    execution: "execution";
+                }>;
+            }, z.core.$strip>>;
+            deepInterview: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                round: z.ZodLiteral<0>;
+                component: z.ZodLiteral<"review-topology">;
+                intent_contract: z.ZodObject<{
+                    items: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        category: z.ZodEnum<{
+                            surface: "surface";
+                            artifact: "artifact";
+                            integration: "integration";
+                            constraint: "constraint";
+                        }>;
+                        statement: z.ZodString;
+                    }, z.core.$strict>>;
+                    confirmation_options: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
                 round_id: z.ZodOptional<z.ZodString>;
+                dimension: z.ZodString;
+                ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodObject<{
                 round: z.ZodNumber;
+                intent_review: z.ZodObject<{
+                    observed_items: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        category: z.ZodEnum<{
+                            surface: "surface";
+                            artifact: "artifact";
+                            integration: "integration";
+                            constraint: "constraint";
+                        }>;
+                        statement: z.ZodString;
+                    }, z.core.$strict>>;
+                    supporting_substitutions: z.ZodArray<z.ZodObject<{
+                        removed_id: z.ZodString;
+                        replacement_ids: z.ZodArray<z.ZodString>;
+                        rationale: z.ZodString;
+                    }, z.core.$strict>>;
+                    approval_options: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
+                round_id: z.ZodOptional<z.ZodString>;
                 component: z.ZodString;
                 dimension: z.ZodString;
                 ambiguity: z.ZodNumber;
-            }, z.core.$strip>>;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodObject<{
+                round_id: z.ZodOptional<z.ZodString>;
+                round: z.ZodNumber;
+                component: z.ZodString;
+                dimension: z.ZodString;
+                ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>]>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly strict = true;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -52,12 +52,12 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.5.1",
-		"@sayknow-cli/agent-core": "0.5.1",
-		"@sayknow-cli/ai": "0.5.1",
-		"@sayknow-cli/natives": "0.5.1",
-		"@sayknow-cli/tui": "0.5.1",
-		"@sayknow-cli/utils": "0.5.1",
+		"@sayknow-cli/stats": "0.5.2",
+		"@sayknow-cli/agent-core": "0.5.2",
+		"@sayknow-cli/ai": "0.5.2",
+		"@sayknow-cli/natives": "0.5.2",
+		"@sayknow-cli/tui": "0.5.2",
+		"@sayknow-cli/utils": "0.5.2",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -124,6 +124,9 @@
 		"./commands/skc-runtime-bridge": null,
 		"./capability/mcp": null,
 		"./config/mcp-schema": null,
+		"./config/model-auth": null,
+		"./config/model-bindings-applier": null,
+		"./config/model-discovery-manager": null,
 		"./discovery/mcp-json": null,
 		"./exa": null,
 		"./exa/*": null,

package/src/commands/session.ts

@@ -1,4 +1,13 @@
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { readBootGeneration } from "../skc-runtime/boot-generation";
+import {
+	decodeRestoreReference,
+	encodeRestoreReference,
+	evaluateRestoreCandidates,
+	listRestorePointers,
+	type RestoreCandidateVerdict,
+} from "../skc-runtime/session-restore";
+import { buildRestoreCandidateDeps, restoreSession } from "../skc-runtime/session-restore-runtime";
 import {
 	attachSkcTmuxSession,
 	createSkcTmuxSession,
@@ -45,12 +54,13 @@ function sessionJson(session: SessionJsonDto): SessionJsonDto {
 }
 
 export default class Session extends Command {
-	static description = "List, inspect, attach, and remove tagged SKC-managed tmux sessions";
+	static description =
+		"List, inspect, attach, and remove tagged SKC-managed tmux sessions. `restore` is a manual, opt-in recovery step that only ever restores sessions this machine can prove died in a REBOOT: nothing starts automatically at login, a session that is still live is never duplicated, and running tools or background work are not recovered — only the tmux session, its directory, and its conversation.";
 	static strict = false;
 
 	static args = {
 		action: Args.string({
-			description: "list (default), status, create, attach, or remove",
+			description: "list (default), status, create, attach, remove, or restore",
 			required: false,
 		}),
 		session: Args.string({
@@ -67,6 +77,15 @@ export default class Session extends Command {
 		"state-file": Flags.string({
 			description: "Expected @skc-session-state-file tag for force-close (defense-in-depth match)",
 		}),
+		"dry-run": Flags.boolean({
+			description:
+				"restore: list candidates and their verdicts. Changes nothing at all (no tmux command, no lock, no database, no pointer write). This is the default when no --reference is given.",
+			default: false,
+		}),
+		reference: Flags.string({
+			description:
+				"restore: restore exactly one candidate by the opaque reference shown in --dry-run output. Refused unless that candidate is still reboot-eligible at this moment.",
+		}),
 	};
 
 	static examples = [
@@ -76,6 +95,8 @@ export default class Session extends Command {
 		"skc session attach <session>",
 		"skc session remove <session>",
 		"skc session force-close <session> --session-id <id>",
+		"skc session restore --dry-run   # list what a reboot left behind",
+		"skc session restore --reference <ref>   # restore exactly that one",
 	];
 
 	async run(): Promise<void> {
@@ -105,6 +126,71 @@ export default class Session extends Command {
 				return;
 			}
 
+			if (action === "restore") {
+				// Manual, reboot-proven, opt-in. Nothing here starts automatically at
+				// login, and a session is only ever restored when this host can prove
+				// the machine rebooted since that session was recorded.
+				const reference = flags.reference;
+				const decoded = reference ? decodeRestoreReference(reference) : null;
+				if (reference && !decoded) throw new Error("invalid_restore_reference");
+				const pointers = listRestorePointers().filter(
+					pointer =>
+						!decoded ||
+						(pointer.coordinator_session_id === decoded.coordinatorSessionId &&
+							pointer.state_file === decoded.stateFile),
+				);
+				if (reference && pointers.length === 0) throw new Error("restore_reference_not_found");
+				const verdicts = evaluateRestoreCandidates(pointers, buildRestoreCandidateDeps(readBootGeneration()));
+				const describe = (verdict: RestoreCandidateVerdict) => ({
+					reference: encodeRestoreReference(verdict.pointer.coordinator_session_id, verdict.pointer.state_file),
+					sessionId: verdict.pointer.skc_session_id,
+					cwd: verdict.pointer.cwd,
+					branch: verdict.pointer.branch,
+					eligible: verdict.eligible,
+					...(verdict.eligible ? {} : { reason: verdict.reason }),
+				});
+				// Dry run is the default reporting surface and performs zero mutation:
+				// no pointer write, no lock, no SQLite, no tmux command.
+				if (flags["dry-run"] || !reference) {
+					const rows = verdicts.map(describe);
+					if (json) {
+						writeJson({ ok: true, dryRun: true, candidates: rows });
+						return;
+					}
+					writeText(
+						rows.length === 0
+							? ["no restore candidates"]
+							: rows.map(row =>
+									[
+										row.eligible ? "restorable" : `skipped(${row.reason})`,
+										row.sessionId,
+										row.cwd,
+										row.reference,
+									].join("\t"),
+								),
+					);
+					return;
+				}
+				const verdict = verdicts[0];
+				if (!verdict) throw new Error("restore_reference_not_found");
+				if (!verdict.eligible) throw new Error(`restore_ineligible_${verdict.reason}`);
+				const outcome = restoreSession(verdict.pointer);
+				if (!outcome.ok) throw new Error(outcome.detail);
+				if (json) {
+					writeJson({
+						ok: true,
+						restored: {
+							sessionId: outcome.pointer.skc_session_id,
+							cwd: outcome.pointer.cwd,
+							tmuxSession: outcome.tmuxSession,
+						},
+					});
+					return;
+				}
+				writeText([`restored: ${outcome.tmuxSession} (${outcome.pointer.skc_session_id})`]);
+				return;
+			}
+
 			if (action === "create") {
 				const session = createSkcTmuxSession();
 				if (json) {

package/src/config/model-registry.ts

@@ -1032,6 +1032,13 @@ export class ModelRegistry {
 	#lastStaticLoadMtime: number | null = null;
 	#registeredProviderSources: Set<string> = new Set();
 	#providerDiscoveryStates: Map<string, ProviderDiscoveryState> = new Map();
+	/**
+	 * Monotonic per-provider discovery sequence. Overlapping refreshes for the
+	 * same provider can complete out of order; only the newest-started refresh
+	 * may publish discovery state or contribute models, so a slow stale fetch
+	 * never overwrites a fresher result.
+	 */
+	#providerDiscoverySequences: Map<string, number> = new Map();
 	#cacheDbPath?: string;
 	#suppressedSelectors: Map<string, number> = new Map();
 	#backgroundRefresh?: Promise<void>;
@@ -1815,11 +1822,15 @@ export class ModelRegistry {
 		providerConfig: DiscoveryProviderConfig,
 		strategy: ModelRefreshStrategy,
 	): Promise<Model<Api>[]> {
+		const sequence = (this.#providerDiscoverySequences.get(providerConfig.provider) ?? 0) + 1;
+		this.#providerDiscoverySequences.set(providerConfig.provider, sequence);
+		const isCurrentDiscovery = () => this.#providerDiscoverySequences.get(providerConfig.provider) === sequence;
 		const cached = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
 		const requiresAuth = !this.#keylessProviders.has(providerConfig.provider);
 		if (requiresAuth) {
 			const apiKey = await this.#peekApiKeyForProvider(providerConfig.provider);
 			if (!isAuthenticated(apiKey)) {
+				if (!isCurrentDiscovery()) return [];
 				this.#providerDiscoveryStates.set(providerConfig.provider, {
 					provider: providerConfig.provider,
 					status: "unauthenticated",
@@ -1865,6 +1876,7 @@ export class ModelRegistry {
 				: result.models.length > 0
 					? "ok"
 					: "empty";
+		if (!isCurrentDiscovery()) return [];
 		this.#providerDiscoveryStates.set(providerId, {
 			provider: providerId,
 			status,

package/src/config/telegram-autostart.ts

@@ -10,11 +10,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getConfigRootDir, isCompiledBinary, logger } from "@sayknow-cli/utils";
-import { settings } from "./settings";
+import { settings as globalSettings, type Settings } from "./settings";
 import type { TelegramSettings } from "./settings-schema";
 import { telegramSettingsToEnv, validateTelegramSettings } from "./telegram-env-bridge";
 
-function readTelegramSettings(): TelegramSettings {
+/**
+ * The startup command runs against an explicit Settings instance (tests and
+ * embedders inject one), so read through it instead of the global proxy —
+ * which may not be initialized at all on those paths.
+ */
+type TelegramSettingsSource = Pick<Settings, "get">;
+
+function readTelegramSettings(settings: TelegramSettingsSource): TelegramSettings {
 	return {
 		enabled: settings.get("telegram.enabled"),
 		botToken: settings.get("telegram.botToken"),
@@ -69,10 +76,10 @@ function isAlreadyRunning(pidFile: string): boolean {
  * it in the background. Never throws — failures are logged as warnings so the
  * main skc session is unaffected.
  */
-export async function maybeAutostartTelegramRemote(): Promise<void> {
+export async function maybeAutostartTelegramRemote(settings: TelegramSettingsSource = globalSettings): Promise<void> {
 	if (!settings.get("telegram.enabled")) return;
 
-	const config = readTelegramSettings();
+	const config = readTelegramSettings(settings);
 	const errors = validateTelegramSettings(config);
 	if (errors.length > 0) {
 		logger.warn("Telegram Remote enabled but misconfigured, skipping autostart", { errors });

package/src/defaults/skc/skills/deep-interview/SKILL.md

@@ -26,7 +26,7 @@ Deep Interview implements Ouroboros-inspired Socratic questioning with mathemati
 <Do_Not_Use_When>
 - User has a detailed, specific request with file paths, function names, or acceptance criteria -- execute directly
 - User wants to explore options or brainstorm -- use `ralplan` skill instead
-- User wants a quick fix or single change -- delegate to executor or execution
+- User wants a quick fix or single change -- delegate to executor or direct execution
 - User says "just do it" or "skip the questions" without an explicit execution path -- respect their intent by ending interview and writing a `pending approval` spec, not by mutating files or delegating execution
 - User already has a PRD or plan file and explicitly asks to execute it -- use the requested execution skill with that plan
 </Do_Not_Use_When>
@@ -128,6 +128,12 @@ If the user request appended after this skill as the final `User:` line is alrea
 
 This gate exists to prevent deep-interview from making easy problems harder. A small verification need does not make a request interview-worthy.
 
+**Implementation wording is not execution approval.** When the user says `implementation`, "implementation plan", Korean `구현`, or "구현 계획", they are describing the eventual target, not permission to implement now. Interpreting that wording as approval is the single most likely way this skill breaks its own boundary.
+
+On that wording: do not implement, edit/write code, launch implementation workers, or start task/skill/ultragoal implementation. Say plainly — "I can interview for an implementation plan, but I won't implement during deep-interview." — and continue clarifying scope, risks, acceptance criteria, and unknowns.
+
+Implementation requires an explicit phase transition/approval after the interview: the workflow phase must explicitly transition out of deep-interview, and execution approval must be captured by a downstream execution path (Phase 5's bridge into `/skill:ralplan`, `/skill:ultragoal`, or `/skill:team`). Wanting an implementation plan and approving implementation are two different consents.
+
 ## Phase 0.75: Optional Trace Pre-Step
 
 Run this phase only when the active deep-interview state or invocation indicates `--trace` / `state.trace.enabled === true`. It is a pre-interview research step, not an implementation phase.
@@ -326,6 +332,20 @@ If any prompt input is too large, summarize it first and then continue from the
 | Context Clarity (brownfield) | "How does this fit?" | "I found JWT auth middleware in `src/auth/` (pattern: passport + JWT). Should this feature extend that path or intentionally diverge from it?" |
 | Scope-fuzzy / ontology stress | "What IS the core thing here?" | "You have named Tasks, Projects, and Workspaces across the last rounds. Which one is the core entity, and which are supporting views or containers?" |
 
+**Attach your own guess to every question.** The question exposes the *user's* assumptions; the guess exposes *yours*. Without it the interview only ever audits one side, and the agent's unexamined read of the ask silently steers the next round's targeting.
+
+Every generated question MUST carry a one-line `GUESS:` — your hypothesis for the answer, the reason you hold it, and what changes if it is wrong:
+
+```
+{question}
+GUESS: {your hypothesis} — {why you hold it}. If it is {the other reading} instead, {what changes}.
+```
+
+- Reacting is cheaper than generating: a terse "no, the second one" still carries a full correction, so low-effort answers stop being low-information rounds.
+- A visible guess is falsifiable. Being wrong out loud is the point; guess in the direction you expect pushback when the reading is genuinely contested.
+- A guess is NOT an auto-answer. It never resolves the round, never feeds scoring, and never increments `auto_answer_streak` — only the user's answer does.
+- Skip only when a guess would be pure noise: Round 0 topology confirmation, the Phase 4b restate gate, and clarification re-asks.
+
 ### Step 2a′: Auto-Research Greenfield Questions
 
 When the next question is for a greenfield interview and is tagged `research: true`, load `auto-research-greenfield.md` as an internal `kind: "skill-fragment"` prompt for a fork-context architect before Step 2b. Pass only the tagged question, locked topology summary, prompt-safe initial idea, trimmed prior decisions/gaps, and relevant constraints. The architect must return 2-3 ranked candidates with rationale, confidence, and fallback notes. Validate the shape before use; if valid, incorporate the candidates as concise answer options or context for the single user-facing question and append the round number to `auto_researched_rounds`. If invalid or unavailable, fall back silently to the normal generated question and increment `architect_failures`.
@@ -340,14 +360,19 @@ Use the `ask` tool with the generated question. When a question has options, you
 Round {n} | Component: {target_component_name} | Targeting: {weakest_dimension} | Why now: {one_sentence_targeting_rationale} | Ambiguity: {score}%
 
 {question}
+GUESS: {your hypothesis} — {why you hold it}. If it is {the other reading} instead, {what changes}.
 ```
 
 Options should include contextually relevant choices plus free-text, translated/localized according to `language.instruction` when present.
 
-After applying `language.instruction` to the visible question, options, and generated rationale, apply the self-proofread once to new prose only; preserve only the Round/Component/Targeting/Ambiguity line structure, fixed labels, numeric ambiguity value, component/target identifiers, and `deepInterview.*` metadata keys. Do not exempt generated natural-language rationale such as Why now.
+After applying `language.instruction` to the visible question, options, and generated rationale, apply the self-proofread once to new prose only; preserve only the Round/Component/Targeting/Ambiguity line structure, fixed labels (including the `GUESS:` marker), numeric ambiguity value, component/target identifiers, and `deepInterview.*` metadata keys. Do not exempt generated natural-language rationale such as Why now or the guess text that follows the `GUESS:` marker.
 
 When calling `ask`, SHOULD include optional structured metadata so the runtime can record the round without manual state writes: `deepInterview.round_id?`, `deepInterview.round`, `deepInterview.component`, `deepInterview.dimension`, and `deepInterview.ambiguity`. Keep this metadata aligned with the visible Round/Component/Targeting/Ambiguity line; if metadata cannot be supplied, the legacy formatted question text remains the fallback.
 
+**Non-behavioral adapter context (`confused_terms`, `references`).** `deepInterview.confused_terms` and `deepInterview.references` carry vocabulary and citations queued at interview start. They are inert: they MUST NOT alter the first question, are never inferred from vocabulary density, and a reference's `url`/`excerpt` are strings that are **never auto-fetched**. Bounds enforced at the ask boundary: at most 32 terms and 32 references, adapter strings ≤ 256 characters, `url`/`excerpt` ≤ 2048, and core round metadata (`round_id`, `component`, `dimension`) ≤ 128 — all counted in Unicode code points, so emoji-padded input hits the same ceiling as ASCII.
+
+**Free-text vs structural input (`FREETEXT_FIELDS`).** The runtime keeps an allowlist of fields that legitimately carry prose — `initial_context`, `initial_idea`, `initial_context_summary`, `user_response`, `answer`, `goal`, `objective`, `prompt`, `description`, `statement`, `restated_goal`, `evidence`, `excerpt`. Inside those fields, shell metacharacters (`;`, `|`, `&`, backticks, `$()`) are valid prose and MUST NOT be rejected as structural injection; a user is allowed to describe a shell command. Structural fields (ids, categories, hashes) stay strictly validated by their own guards. Size is capped by character-count, not byte length: 50,000 for initial context and 10,000 for a single user response.
+
 If the `ask` tool returns `clarificationQuestion`, treat it as a non-answer about the displayed choices. Answer the clarification briefly from the current interview context, then call `ask` again with the exact original question, options, and `deepInterview.*` metadata. A clarification bypasses Step 2b′ auto-answer, Step 2b″ free-text refine, Step 2c ambiguity scoring, Step 2d progress reporting, and Step 2e state updates; it must not be recorded as a round answer. This does not violate the one-question-per-round rule because the round remains unresolved until the user submits a real listed option or `Other` answer.
 
 ### Step 2b′: Auto-Answer Opted-Out Questions
@@ -504,7 +529,7 @@ Round {n} complete.
 
 Apply `language.instruction` when present before showing this progress report so status text, gaps, and next-target phrasing stay in the preserved session language.
 
-Then apply the self-proofread once (DIPP-5) to narrative status text, generated prose cells, gaps, and next-target phrasing; preserve only table structure, fixed status labels, scores, weights, component ids, and trigger tokens.
+Then apply the self-proofread once to narrative status text, generated prose cells, gaps, and next-target phrasing; preserve only table structure, fixed status labels, scores, weights, component ids, and trigger tokens.
 
 ### Step 2e: Update State
 
@@ -927,6 +952,7 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 - [ ] Oversized initial context/history summarized before scoring, question generation, spec generation, or handoff
 - [ ] Round 0 topology gate completed before scoring; `topology.confirmed_at` persisted
 - [ ] Ambiguity scored and displayed every round, naming the weakest component/dimension target (rotating across active components when N > 1)
+- [ ] Every asked question carried a `GUESS:` line (except Round 0 topology, the Restate gate, and clarification re-asks), and no guess was recorded as an answer or counted toward `auto_answer_streak`
 - [ ] Lateral panel convened at milestone transitions (and before synthesizing agent-supplied answers) with parallel read-only personas
 - [ ] Free-text answers passed the Refine gate; dialectic rhythm guard forced a user question after 3 agent-resolved answers; any auto-answer threshold crossing explicitly confirmed
 - [ ] Closure / Acceptance Guard and the one-sentence Restate gate both passed before crystallization