@sayknow-cli/coding-agent 0.3.2 → 0.3.5

package/src/skc-runtime/ultragoal-runtime.ts

@@ -1,4 +1,5 @@
 import * as crypto from "node:crypto";
+import * as os from "node:os";
 import * as path from "node:path";
 import { inflateSync } from "node:zlib";
 import { normalizeGoal } from "../goals/state";
@@ -11,7 +12,13 @@ import { sessionUltragoalDir, skcRoot } from "./session-layout";
 import { resolveSkcSessionForRead, resolveSkcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
 import { reconcileWorkflowSkillState } from "./state-runtime";
-import { appendJsonl, persistedStateRevision, writeArtifact, writeGuardedJsonAtomic } from "./state-writer";
+import {
+	appendJsonl,
+	persistedStateRevision,
+	withWorkflowStateLock,
+	writeArtifact,
+	writeGuardedJsonAtomic,
+} from "./state-writer";
 
 export type UltragoalSkcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus =
@@ -80,6 +87,44 @@ export interface UltragoalLedgerEvent extends JsonObject {
 	timestamp?: string;
 }
 
+export type UltragoalNudgeSurface = "pause" | "drop" | "ask" | "premature_complete";
+export type UltragoalNudgeTargetKind = "story" | "final_aggregate_receipt";
+
+export interface UltragoalNudgeLedgerEvent extends UltragoalLedgerEvent {
+	event: "nudge";
+	goalId: string;
+	targetKind: UltragoalNudgeTargetKind;
+	surface: UltragoalNudgeSurface;
+	attempt: number;
+	budget: number;
+	reason: string;
+	currentGoalObjective?: string;
+}
+
+export interface UltragoalNudgeTarget {
+	goalId: string;
+	targetKind: UltragoalNudgeTargetKind;
+}
+
+export type UltragoalNudgeOutcome =
+	| {
+			nudged: true;
+			attempt: number;
+			budget: number;
+			goalId: string;
+			targetKind: UltragoalNudgeTargetKind;
+			event: UltragoalNudgeLedgerEvent;
+	  }
+	| {
+			nudged: false;
+			exhausted: true;
+			count: number;
+			budget: number;
+			goalId: string;
+			targetKind: UltragoalNudgeTargetKind;
+	  }
+	| { nudged: false; inactive: true; reason: string };
+
 export interface UltragoalPaths {
 	dir: string;
 	briefPath: string;
@@ -95,6 +140,11 @@ export interface UltragoalStatusSummary {
 	currentGoal?: UltragoalGoal;
 	counts: Record<UltragoalGoalStatus, number>;
 	goals: UltragoalGoal[];
+	nudgeBudget?: number;
+	nudgeCount?: number;
+	nudgeRemaining?: number;
+	nudgeGoalId?: string;
+	nudgeTargetKind?: UltragoalNudgeTargetKind;
 }
 
 export interface UltragoalCommandResult {
@@ -220,6 +270,156 @@ export async function readUltragoalLedger(cwd: string, sessionId?: string | null
 	}
 }
 
+export const DEFAULT_ULTRAGOAL_NUDGE_BUDGET = 10;
+
+/** Pure: count ledger `nudge` rows for an exact goalId. */
+export function countUltragoalNudges(ledger: readonly UltragoalLedgerEvent[], goalId: string): number {
+	return ledger.filter(event => event.event === "nudge" && event.goalId === goalId).length;
+}
+
+function parseNudgeBudgetValue(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+async function readSettingsNudgeBudget(settingsPath: string): Promise<number | null> {
+	try {
+		const raw = await Bun.file(settingsPath).text();
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		// Support both the flat dotted key and a nested skc.ultragoal.nudgeBudget shape.
+		const flat = parseNudgeBudgetValue(parsed["skc.ultragoal.nudgeBudget"]);
+		if (flat !== null) return flat;
+		const skc = parsed.skc;
+		if (skc && typeof skc === "object") {
+			const ultragoal = (skc as Record<string, unknown>).ultragoal;
+			if (ultragoal && typeof ultragoal === "object") {
+				return parseNudgeBudgetValue((ultragoal as Record<string, unknown>).nudgeBudget);
+			}
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the per-story nudge budget. Project `./.skc/settings.json` overrides the
+ * user settings (`$SKC_CONFIG_DIR/settings.json` or `~/.skc/settings.json`), else the
+ * default. Mirrors the `skc.deepInterview.ambiguityThreshold` user+project precedence.
+ */
+export async function resolveUltragoalNudgeBudget(cwd: string): Promise<{ budget: number; source: string }> {
+	const projectPath = path.join(skcRoot(cwd), "settings.json");
+	const project = await readSettingsNudgeBudget(projectPath);
+	if (project !== null) return { budget: project, source: projectPath };
+	const userDir = process.env.SKC_CONFIG_DIR?.trim() || path.join(os.homedir(), ".skc");
+	const userPath = path.join(userDir, "settings.json");
+	const user = await readSettingsNudgeBudget(userPath);
+	if (user !== null) return { budget: user, source: userPath };
+	return { budget: DEFAULT_ULTRAGOAL_NUDGE_BUDGET, source: "default" };
+}
+
+/**
+ * Pure canonical selector shared by guards and status so `nudgeGoalId` can never
+ * diverge between what a guard consumes and what status displays. Prefers the active
+ * current-goal objective, then active > pending > failed (matching `chooseNextGoal`),
+ * then the aggregate final-receipt target when all stories are complete but the
+ * aggregate run still needs a final receipt. Returns null for verified-complete or
+ * absent/unrelated plans.
+ */
+export function selectUltragoalNudgeTarget(
+	plan: UltragoalPlan,
+	options: { currentGoalObjective?: string; retryFailed?: boolean } = {},
+): UltragoalNudgeTarget | null {
+	const objective = options.currentGoalObjective?.trim();
+	if (objective) {
+		const matched = plan.goals.find(
+			goal => goal.objective.trim() === objective && SCHEDULABLE_STATUSES.has(goal.status),
+		);
+		if (matched) return { goalId: matched.id, targetKind: "story" };
+	}
+	const next = chooseNextGoal(plan, options.retryFailed === true);
+	if (next) return { goalId: next.id, targetKind: "story" };
+	const completion = getUltragoalRunCompletionState(plan, { retryFailed: options.retryFailed });
+	if (completion.needsFinalAggregateReceipt) {
+		const required = requiredUltragoalGoals(plan);
+		const finalGoal = required.at(-1);
+		if (finalGoal) return { goalId: finalGoal.id, targetKind: "final_aggregate_receipt" };
+	}
+	return null;
+}
+
+/**
+ * Atomic consuming writer. Locks the ledger path, rereads + counts nudge rows for the
+ * target story, and appends exactly one `nudge` row inside the same critical section
+ * only while budget remains. Reuses the lockless `appendLedger` inside the lock (it
+ * does not acquire a conflicting lock), so concurrent guarded attempts cannot both
+ * observe `count = budget - 1` and overshoot the budget.
+ */
+export async function recordUltragoalNudgeIfBudgetRemaining(input: {
+	cwd: string;
+	sessionId?: string | null;
+	target: UltragoalNudgeTarget;
+	surface: UltragoalNudgeSurface;
+	budget: number;
+	reason: string;
+	currentGoalObjective?: string;
+}): Promise<UltragoalNudgeOutcome> {
+	const { cwd, sessionId, target, surface, budget, reason } = input;
+	if (!Number.isFinite(budget) || budget <= 0) {
+		return {
+			nudged: false,
+			exhausted: true,
+			count: 0,
+			budget: Math.max(0, budget | 0),
+			goalId: target.goalId,
+			targetKind: target.targetKind,
+		};
+	}
+	const resolvedSessionId =
+		sessionId?.trim() || resolveSkcSessionForWrite(cwd, { envSessionId: process.env.SKC_SESSION_ID }).skcSessionId;
+	const paths = getUltragoalPaths(cwd, resolvedSessionId);
+	return withWorkflowStateLock(
+		paths.ledgerPath,
+		async () => {
+			const ledger = await readUltragoalLedger(cwd, resolvedSessionId);
+			const count = countUltragoalNudges(ledger, target.goalId);
+			if (count >= budget) {
+				return {
+					nudged: false,
+					exhausted: true,
+					count,
+					budget,
+					goalId: target.goalId,
+					targetKind: target.targetKind,
+				} as const;
+			}
+			const attempt = count + 1;
+			const entry = (await appendLedger(
+				cwd,
+				{
+					event: "nudge",
+					goalId: target.goalId,
+					targetKind: target.targetKind,
+					surface,
+					attempt,
+					budget,
+					reason,
+					...(input.currentGoalObjective ? { currentGoalObjective: input.currentGoalObjective } : {}),
+				},
+				resolvedSessionId,
+			)) as UltragoalNudgeLedgerEvent;
+			return {
+				nudged: true,
+				attempt,
+				budget,
+				goalId: target.goalId,
+				targetKind: target.targetKind,
+				event: entry,
+			} as const;
+		},
+		{ cwd },
+	);
+}
+
 async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void> {
 	const resolvedSessionId =
 		sessionId?.trim() || resolveSkcSessionForWrite(cwd, { envSessionId: process.env.SKC_SESSION_ID }).skcSessionId;
@@ -525,6 +725,20 @@ export async function getUltragoalStatus(cwd: string, sessionId?: string | null)
 	else if (counts.active > 0) status = "active";
 	else if (counts.failed > 0) status = "failed";
 	else if (counts.blocked > 0 || counts.review_blocked > 0) status = "blocked";
+	const nudgeTarget = selectUltragoalNudgeTarget(plan, { currentGoalObjective: currentGoal?.objective });
+	let nudgeFields: Partial<UltragoalStatusSummary> = {};
+	if (nudgeTarget) {
+		const { budget } = await resolveUltragoalNudgeBudget(cwd);
+		const ledger = await readUltragoalLedger(cwd, resolvedSessionId);
+		const nudgeCount = countUltragoalNudges(ledger, nudgeTarget.goalId);
+		nudgeFields = {
+			nudgeBudget: budget,
+			nudgeCount,
+			nudgeRemaining: Math.max(0, budget - nudgeCount),
+			nudgeGoalId: nudgeTarget.goalId,
+			nudgeTargetKind: nudgeTarget.targetKind,
+		};
+	}
 	return {
 		exists: true,
 		status,
@@ -533,6 +747,7 @@ export async function getUltragoalStatus(cwd: string, sessionId?: string | null)
 		currentGoal,
 		counts,
 		goals: plan.goals,
+		...nudgeFields,
 	};
 }
 export function buildUltragoalHudSummary(
@@ -3847,6 +4062,11 @@ async function reconcileUltragoalState(cwd: string): Promise<void> {
 			goals_path: summary.paths.goalsPath,
 		};
 		if (summary.skcObjective) payload.skc_objective = summary.skcObjective;
+		if (summary.nudgeBudget !== undefined) payload.nudge_budget = summary.nudgeBudget;
+		if (summary.nudgeCount !== undefined) payload.nudge_count = summary.nudgeCount;
+		if (summary.nudgeRemaining !== undefined) payload.nudge_remaining = summary.nudgeRemaining;
+		if (summary.nudgeGoalId !== undefined) payload.nudge_goal_id = summary.nudgeGoalId;
+		if (summary.nudgeTargetKind !== undefined) payload.nudge_target_kind = summary.nudgeTargetKind;
 		const ledgerText = await Bun.file(summary.paths.ledgerPath)
 			.text()
 			.catch(() => "");

package/src/tools/browser/tab-supervisor.ts

@@ -57,6 +57,10 @@ export interface TabSession {
 	kindTag: BrowserKindTag;
 	/** Session that acquired this tab; used for session-scoped teardown (F13). */
 	ownerId?: string;
+	/** Unix-ms timestamp of the last acquire/run activity; drives GC idle + LRU ordering. */
+	lastUsedAt: number;
+	/** Set synchronously by the shared begin-release guard so concurrent release is a no-op. */
+	releasing?: boolean;
 }
 
 export interface AcquireTabOptions {
@@ -94,6 +98,76 @@ export function getTab(name: string): TabSession | undefined {
 	return tabs.get(name);
 }
 
+/**
+ * Shared synchronous begin-release guard. Returns true for the first caller (which then
+ * owns teardown) and false for any concurrent/repeat caller, so `releaseBrowser` and the
+ * `BrowserHandle.refCount` decrement happen exactly once even when the idle sweep, the RSS
+ * sweep, a manual close, and `forceKillTab` race on the same tab.
+ */
+function beginRelease(tab: TabSession): boolean {
+	if (tab.releasing) return false;
+	tab.releasing = true;
+	return true;
+}
+
+/** Read-only, GC-facing projection of a live tab. Never exposes the mutable `tabs` map. */
+export interface TabGcSnapshot {
+	name: string;
+	ownerId?: string;
+	state: TabSession["state"];
+	pendingCount: number;
+	kindTag: BrowserKindTag;
+	lastUsedAt: number;
+	browserRefCount: number;
+}
+
+export interface BrowserGcEligibilityPolicy {
+	now: () => number;
+	idleMs: number;
+}
+
+/** Snapshot every live tab for GC ordering/diagnostics. */
+export function listTabsForGc(): TabGcSnapshot[] {
+	return [...tabs.values()].map(tab => ({
+		name: tab.name,
+		ownerId: tab.ownerId,
+		state: tab.state,
+		pendingCount: tab.pending.size,
+		kindTag: tab.kindTag,
+		lastUsedAt: tab.lastUsedAt,
+		browserRefCount: tab.browser.refCount,
+	}));
+}
+
+/**
+ * Evict a tab only if it is still GC-eligible against the LIVE supervisor state. The full
+ * predicate is checked synchronously and `releaseTab` is invoked with no intervening await,
+ * so a tab that became busy after a GC snapshot cannot be closed (its run rejected). Returns
+ * true only when the tab was actually released.
+ */
+export async function releaseTabIfGcEligible(name: string, policy: BrowserGcEligibilityPolicy): Promise<boolean> {
+	const tab = tabs.get(name);
+	if (!tab) return false;
+	if (tab.releasing) return false;
+	if (tab.state !== "alive") return false;
+	if (tab.pending.size !== 0) return false;
+	if (tab.kindTag !== "headless" && tab.kindTag !== "spawned") return false;
+	if (policy.now() - tab.lastUsedAt <= policy.idleMs) return false;
+	// All predicates passed synchronously; releaseTab applies the shared begin-release guard
+	// on the same microtask, so no other code runs between the check and the state transition.
+	return await releaseTab(name, { kill: false });
+}
+
+/** Test-only: install a fabricated tab session. */
+export function setTabForTest(tab: TabSession): void {
+	tabs.set(tab.name, tab);
+}
+
+/** Test-only: clear the tab registry between cases. */
+export function clearTabsForTest(): void {
+	tabs.clear();
+}
+
 export async function acquireTab(
 	name: string,
 	browser: BrowserHandle,
@@ -105,6 +179,7 @@ export async function acquireTab(
 			if (opts.dialogs !== undefined && opts.dialogs !== existing.dialogPolicy) {
 				await releaseTab(name, { kill: false });
 			} else {
+				existing.lastUsedAt = Date.now();
 				if (opts.url) {
 					await runInTabWithSnapshot(
 						name,
@@ -166,6 +241,7 @@ export async function acquireTab(
 		dialogPolicy: opts.dialogs,
 		kindTag: browser.kind.kind,
 		ownerId: opts.ownerId,
+		lastUsedAt: Date.now(),
 	};
 	worker.onMessage(msg => handleTabMessage(tab, msg));
 	tabs.set(name, tab);
@@ -188,6 +264,7 @@ async function runInTabWithSnapshot(
 	const tab = tabs.get(name);
 	if (!tab || tab.state === "dead") throw new ToolError(`Tab ${JSON.stringify(name)} is not alive. Reopen it.`);
 	if (tab.pending.size > 0) throw new ToolError(`Tab ${JSON.stringify(name)} is busy`);
+	tab.lastUsedAt = Date.now();
 	const id = Snowflake.next();
 	const { promise, resolve, reject } = Promise.withResolvers<RunResultOk>();
 	const pending: PendingRun = {
@@ -224,6 +301,10 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 		logger.debug("releaseTab: unknown tab", { name });
 		return false;
 	}
+	if (!beginRelease(tab)) {
+		logger.debug("releaseTab: already releasing", { name });
+		return false;
+	}
 	const wasAlive = tab.state === "alive";
 	tab.state = "dead";
 	const closeError = new ToolError(`Tab ${JSON.stringify(name)} was closed`);
@@ -246,7 +327,9 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 	await tab.worker.terminate().catch(() => undefined);
 	if (forced && tab.kindTag === "headless") await closeOrphanTarget(tab);
 	await releaseBrowser(tab.browser, { kill: opts.kill ?? false });
-	tabs.delete(name);
+	// Only delete if the map still holds THIS tab: a same-name reacquire during our async
+	// teardown may have installed a fresh tab that we must not evict.
+	if (tabs.get(name) === tab) tabs.delete(name);
 	return true;
 }
 
@@ -392,6 +475,7 @@ function toErrorPayload(error: unknown): RunErrorPayload {
 async function forceKillTab(name: string, reason: string): Promise<void> {
 	const tab = tabs.get(name);
 	if (!tab) return;
+	if (!beginRelease(tab)) return;
 	tab.state = "dead";
 	const error = new ToolError(reason);
 	for (const pending of tab.pending.values()) pending.reject(error);
@@ -399,7 +483,7 @@ async function forceKillTab(name: string, reason: string): Promise<void> {
 	await tab.worker.terminate().catch(() => undefined);
 	if (tab.kindTag === "headless") await closeOrphanTarget(tab);
 	await releaseBrowser(tab.browser, { kill: false });
-	tabs.delete(name);
+	if (tabs.get(name) === tab) tabs.delete(name);
 }
 
 async function closeOrphanTarget(tab: TabSession): Promise<void> {

package/src/tools/computer-gc.ts

@@ -0,0 +1,66 @@
+import type { Dirent } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@sayknow-cli/utils";
+
+/** Prefix of every computer-use screenshot fallback directory created under the OS temp dir. */
+export const SCREENSHOT_FALLBACK_DIR_PREFIX = "skc-computer-screenshots-";
+
+let screenshotFallbackDirsCreated = false;
+
+/** Lazy-arm marker: called when the first screenshot fallback dir is created this process. */
+export function markScreenshotFallbackDirCreatedForGc(): void {
+	screenshotFallbackDirsCreated = true;
+}
+
+/** Whether any screenshot fallback dir has been created this process (GC lazy-arm gate). */
+export function hasCreatedScreenshotFallbackDir(): boolean {
+	return screenshotFallbackDirsCreated;
+}
+
+/** Test-only: reset the lazy-arm marker between cases. */
+export function resetScreenshotFallbackGcForTest(): void {
+	screenshotFallbackDirsCreated = false;
+}
+
+export interface ScreenshotGcOptions {
+	now: () => number;
+	staleMs: number;
+	/** Base dir to scan; defaults to os.tmpdir(). Injectable for tests. */
+	tmpDir?: string;
+}
+
+/**
+ * Disk-only GC for stale computer-use screenshot fallback directories. Scans the temp dir for
+ * `skc-computer-screenshots-*` directories and removes those whose mtime is older than `staleMs`.
+ * Never throws on a per-directory failure; the whole sweep is best-effort.
+ */
+export async function cleanupStaleScreenshotFallbackDirs(
+	options: ScreenshotGcOptions,
+): Promise<{ scanned: number; removed: number }> {
+	const base = options.tmpDir ?? os.tmpdir();
+	const entries: Dirent[] = await fs.readdir(base, { withFileTypes: true }).catch(err => {
+		logger.debug("screenshot GC: failed to read temp dir", { base, error: (err as Error).message });
+		return [] as Dirent[];
+	});
+
+	const now = options.now();
+	let scanned = 0;
+	let removed = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		if (!entry.name.startsWith(SCREENSHOT_FALLBACK_DIR_PREFIX)) continue;
+		scanned++;
+		const dir = path.join(base, entry.name);
+		try {
+			const stat = await fs.stat(dir);
+			if (now - stat.mtimeMs <= options.staleMs) continue;
+			await fs.rm(dir, { recursive: true, force: true });
+			removed++;
+		} catch (err) {
+			logger.debug("screenshot GC: failed to remove stale dir", { dir, error: (err as Error).message });
+		}
+	}
+	return { scanned, removed };
+}

package/src/tools/computer.ts

@@ -7,6 +7,7 @@ import { prompt } from "@sayknow-cli/utils";
 import * as z from "zod/v4";
 import computerDescription from "../prompts/tools/computer.md" with { type: "text" };
 import { resizeImage } from "../utils/image-resize";
+import { markScreenshotFallbackDirCreatedForGc } from "./computer-gc";
 import type { ToolSession } from "./index";
 import type { OutputMeta } from "./output-meta";
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
@@ -547,6 +548,7 @@ function getScreenshotFallbackDir(session: ToolSession): Promise<string> {
 async function createScreenshotFallbackDir(): Promise<string> {
 	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "skc-computer-screenshots-"));
 	await fs.chmod(dir, 0o700);
+	markScreenshotFallbackDirCreatedForGc();
 	return dir;
 }