@gajae-code/coding-agent 0.11.10 → 0.12.0

package/src/modes/utils/ui-helpers.ts

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@gajae-code/agent-core";
 import type { AssistantMessage, ImageContent, Message } from "@gajae-code/ai";
-import { type Component, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@gajae-code/tui";
+import { type Component, Loader, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@gajae-code/tui";
 import { settings } from "../../config/settings";
 import { resolveSubskillActivationForSkillInvocation } from "../../extensibility/gjc-plugins";
 import { buildSkillPromptMessage, parseSkillInvocations } from "../../extensibility/skills";
@@ -85,6 +85,99 @@ export function prepareTranscriptRebuild(ui: TUI, policy: TranscriptRebuildPolic
 	if (policy === "replace-identity") ui.resetViewportAnchorIntent();
 	else ui.prepareViewportAnchorForTranscriptRebuild();
 }
+
+export const RESUME_PROGRESS_COMMIT_TIMEOUT_MS = 250;
+
+export interface ResumeProgressLease {
+	readonly committed: Promise<boolean>;
+	clear(): void;
+}
+
+/**
+ * Mount a resume loader on the live status rail and wait for its render generation
+ * to commit before session I/O begins. The commit is advisory: a stopped or
+ * unavailable terminal resolves false and callers continue without blocking.
+ *
+ * Fail open (no-op lease, committed=false) when the status rail or UI lacks the
+ * child-mutation/render-commit surface required to mount progress. Headless and
+ * minimal controller contexts keep resume/migration semantics; full interactive
+ * TUI containers retain progress-before-switch.
+ */
+export function acquireResumeProgressLease(
+	ctx: Pick<InteractiveModeContext, "ui" | "statusContainer">,
+): ResumeProgressLease {
+	if (!canMountResumeProgressLease(ctx)) {
+		return {
+			committed: Promise.resolve(false),
+			clear(): void {},
+		};
+	}
+
+	const statusContainer = ctx.statusContainer as ResumeProgressStatusSurface;
+	const ui = ctx.ui as ResumeProgressUiSurface;
+	const loader = new Loader(
+		ui,
+		spinner => theme?.fg?.("accent", spinner) ?? spinner,
+		message => theme?.fg?.("muted", message) ?? message,
+		"Resuming session…",
+	);
+	statusContainer.addChild(loader);
+	const generation = ui.requestRenderWithGeneration(false, "resume-progress");
+	let active = true;
+	const committed = ui.waitForRenderCommit(generation, RESUME_PROGRESS_COMMIT_TIMEOUT_MS).catch(() => false);
+	return {
+		committed,
+		clear(): void {
+			if (!active) return;
+			active = false;
+			if (statusContainer.children.includes(loader)) statusContainer.removeChild(loader);
+			else loader.stop();
+			ui.requestRender(false, "resume-progress-clear");
+		},
+	};
+}
+
+type ResumeProgressStatusSurface = {
+	addChild: (child: Component) => void;
+	removeChild: (child: Component) => void;
+	children: Component[];
+};
+
+type ResumeProgressUiSurface = InteractiveModeContext["ui"] & {
+	requestRenderWithGeneration: (force?: boolean, source?: string) => number;
+	waitForRenderCommit: (generation: number, timeoutMs?: number) => Promise<boolean>;
+	requestRender: (force?: boolean, source?: string) => void;
+};
+
+function canMountResumeProgressLease(ctx: Pick<InteractiveModeContext, "ui" | "statusContainer">): boolean {
+	const status = ctx.statusContainer as
+		| Partial<{
+				addChild: unknown;
+				removeChild: unknown;
+				children: unknown;
+		  }>
+		| null
+		| undefined;
+	const ui = ctx.ui as
+		| Partial<{
+				requestRenderWithGeneration: unknown;
+				waitForRenderCommit: unknown;
+				requestRender: unknown;
+		  }>
+		| null
+		| undefined;
+
+	return (
+		!!status &&
+		typeof status.addChild === "function" &&
+		typeof status.removeChild === "function" &&
+		Array.isArray(status.children) &&
+		!!ui &&
+		typeof ui.requestRenderWithGeneration === "function" &&
+		typeof ui.waitForRenderCommit === "function" &&
+		typeof ui.requestRender === "function"
+	);
+}
 type TextBlock = { type: "text"; text: string };
 interface RenderInitialMessagesOptions {
 	preserveExistingChat?: boolean;

package/src/prompts/agents/architect.md

@@ -37,11 +37,19 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 {{restrictedBash}}
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
-- Never approve CRITICAL or HIGH severity issues.
+- Never approve carryover CRITICAL or HIGH severity issues (raised in a prior pass and still unresolved). A fresh CRITICAL/HIGH minted from pass 2 on previously-approved ground blocks only with an explicit why-not-visible-earlier justification (rule 2); without that justification, record it as a non-blocking caveat with its severity noted. On pass 1 every CRITICAL/HIGH blocks.
 - Do not skip spec compliance to jump to style nitpicks.
 - Be constructive: explain why an issue matters and how to fix it or strengthen the design.
 </constraints>
 
+<re_review_ratchet>
+- Rule 1 (delta-only): from pass 2, review only the delta against the prior pass plus the resolution of previously raised findings; do not re-litigate previously-approved ground. The prior pass is identified by the re-review context bundle: prior reviewed-plan path, prior same-lane review path, and the explicit run-level pass number supplied in the assignment.
+- Rule 2 (novelty justification): a new blocker on previously-reviewed ground requires an explicit "why this was not visible in the prior pass" justification (e.g. revealed by a fix, new file evidence); without it, demote to a non-blocking caveat.
+- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, neither Architectural Status (`CLEAR`/`WATCH`/`BLOCK`) nor Code Review Recommendation (`APPROVE`/`COMMENT`/`REQUEST CHANGES`) may worsen absent a rule-2-justified new blocker.
+- Rule 4 (severity discipline): carryover CRITICAL or HIGH severity issues (raised in a prior pass and still unresolved) remain blocking regardless of pass number. A fresh CRITICAL/HIGH minted from pass 2 on previously-approved ground blocks only with an explicit why-not-visible-earlier justification (rule 2); without that justification, record it as a non-blocking caveat with its severity noted. On pass 1 every CRITICAL/HIGH blocks.
+- Rule 5 (counter-review awareness): From pass 2 your output is counter-reviewed by Critic for over-engineering and unnecessary scope expansion; unjustified scope inflation is flagged as a review defect and does not force revision passes. On pass 2+, do not broaden scope, add options, or demand synthesis beyond what resolves prior findings; constructive synthesis (Stage 3) stays full-strength on pass 1 only.
+</re_review_ratchet>
+
 <review_stages>
 1. Understand the request, spec, plan, or diff.
 2. Gather file-backed evidence.

package/src/prompts/agents/critic.md

@@ -32,6 +32,15 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - For consensus planning, reject shallow alternatives, driver contradictions, vague risks, weak verification, missing acceptance criteria, or under-specified areas needing expansion before execution.
 </constraints>
 
+<re_review_ratchet>
+- Rule 1 (delta-only): from pass 2, review only the delta against the prior pass plus the resolution of previously raised findings; do not re-litigate previously-approved ground. The prior pass is identified by the re-review context bundle (WI-3): prior reviewed-plan path, prior same-lane review path, and the explicit run-level pass number supplied in the assignment.
+- Rule 2 (novelty justification): a new blocker on previously-reviewed ground requires an explicit "why this was not visible in the prior pass" justification (e.g. revealed by a fix, new file evidence); without it, demote to a non-blocking caveat.
+- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, the verdict must not worsen (e.g. ITERATE -> REJECT) absent a rule-2-justified new blocker.
+- Rule 4 (severity discipline): carryover blockers (raised in a prior pass, still unresolved) remain blocking regardless of pass number. A fresh high-severity concern minted from pass 2 on previously-approved ground follows rule 2: it blocks only with the why-not-visible-earlier justification, else it is recorded as a non-blocking caveat with severity noted.
+- Rule 5 (counter-review duty): from pass 2, Critic also reviews the Architect output (routed via the context bundle) for over-engineering and unnecessary scope expansion; flag inflation as a review defect and do NOT convert unjustified Architect demands into ITERATE — inflating demands must not force revision passes.
+- Enrichment lane ("spec too thin — expand") preserved verbatim but justification-gated from pass 2: expansion requests on already-reviewed ground need the rule-2 justification.
+</re_review_ratchet>
+
 <execution_loop>
 1. Read the plan and referenced artifacts.
 2. Extract and verify file references.

package/src/prompts/agents/executor.md

@@ -34,7 +34,7 @@ Explore just enough context, implement the smallest correct change, and leave co
 {{#if ultragoalRedTeam}}
 
 <ultragoal_red_team_mode>
-This mode activates only when the assignment explicitly labels Executor as Ultragoal completion QA/red-team or asks for `executorQa` red-team evidence. Otherwise, preserve ordinary Executor behavior.
+This mode activates only when the task sets typed `executionMode: "ultragoal-red-team"`, or — as a compatibility fallback — when the assignment text explicitly labels Executor as Ultragoal completion QA/red-team or asks for `executorQa` red-team evidence (not a bare `executorQa` field-name mention). Prefer the typed flag. Otherwise, preserve ordinary Executor behavior.
 
 When active:
 - Follow the exact `executorQa` contract provided in the assignment (matrix shape, row fields, artifact/replay rules); the runtime validates it strictly. If the assignment omits the contract, read the ultragoal SKILL's executor QA section before producing evidence.

package/src/prompts/system/system-prompt.md

@@ -24,7 +24,6 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 - Informational questions are answer-only/read-only unless the user explicitly requests a change, command, or execution.
 - Vague requirements use `/skill:deep-interview`: a requirements-only workflow that must not mutate product code. Its spec hands off as deep-interview → ralplan consensus → pending approval → separately approved execution.
 - Clear work with non-trivial architecture or sequencing risk uses `/skill:ralplan --deliberate` and stops pending approval.
-- Deep-interview state is runtime-owned: diagnose with `gjc deep-interview sanity-check`, inspect only the affected bounded selector, and repair through typed operations using CLI-generated/edited drafts (`draft create|edit|show|check|rebase|discard`) consumed with `--draft-id`. Inline JSON request flags are compatibility-only; normal flow must never reconstruct a payload or full envelope.
 - Use `/skill:ultragoal` for durable goal ledgers and `/skill:team` for approved coordinated persistent work.
 - Delegate large implementation slices to `executor`; use `planner`, `architect`, or `critic` for bounded planning and review.
 - Active skills are authoritative: never ignore an invoked skill; read the full skill text and follow it exactly.

package/src/prompts/tools/read.md

@@ -9,12 +9,13 @@ Read files, directories, archives, SQLite databases, images, documents, internal
 ## Parameters
 
 - `path` — required. Local path, internal URI (`agent://`, `artifact://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: {{TRUNCATION_DEFAULT}} (factory default: `last`); non-file routes such as URLs, directories and converted documents default to `head`. A line-range selector still bounds the selection — this only picks which end of that selection survives the byte/line cap. SQLite row queries page via their own `limit`/`offset` and ignore it.
 
-## Selectors
 
+## Selectors
 Append `:<sel>` to `path`. The bare path falls back to the default mode.
 
-- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
+- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about {{RECEIPT_LINES}} lines or {{RECEIPT_KIB}} KiB, whichever is smaller; the configured truncation direction is {{TRUNCATION_DEFAULT}} (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger {{DEFAULT_MAX_LINES}}-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.
 - `:50` / `:50-` — read from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
 - `:50+150` — 150 lines starting at line 50.
@@ -39,6 +40,7 @@ Append `:<sel>` to `path`. The bare path falls back to the default mode.
   `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`
 
   If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.
+- Directional windows identify the retained first/last lines and the omitted range; use the `re-read <path>:1-<total>` or `:raw` hint in the footer to recover the full content.
 
 # Documents & Notebooks
 

package/src/runtime/memory-domain.ts

@@ -0,0 +1,66 @@
+import type {
+	MemoryGuardDomainSnapshot,
+	MemoryGuardWorkerAccounting,
+	MemoryGuardWorkerSample,
+} from "./memory-guard-contract";
+
+export interface MemoryGuardDomainInput {
+	effectiveLimitBytes: number;
+	totalUsageBytes: number;
+	parentBytes: number;
+	parentReserveBytes: number;
+	workers: readonly MemoryGuardWorkerSample[];
+}
+
+function assertNonNegativeSafeInteger(name: string, value: number): number {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`invalid_${name}`);
+	return value;
+}
+
+function sumWorkerBytes(workers: readonly MemoryGuardWorkerSample[]): number {
+	let total = 0;
+	for (const worker of workers) {
+		total += assertNonNegativeSafeInteger(`worker_bytes:${worker.workerId}`, worker.bytes);
+		if (!Number.isSafeInteger(total)) throw new Error("invalid_worker_total_bytes");
+	}
+	return total;
+}
+
+export function computeMemoryGuardDomain(input: MemoryGuardDomainInput): MemoryGuardDomainSnapshot {
+	const effectiveLimitBytes = assertNonNegativeSafeInteger("effective_limit_bytes", input.effectiveLimitBytes);
+	const totalUsageBytes = assertNonNegativeSafeInteger("total_usage_bytes", input.totalUsageBytes);
+	const parentBytes = assertNonNegativeSafeInteger("parent_bytes", input.parentBytes);
+	const parentReserveBytes = assertNonNegativeSafeInteger("parent_reserve_bytes", input.parentReserveBytes);
+	const totalWorkerBytes = sumWorkerBytes(input.workers);
+	const acceptedWorkers = input.workers.filter(worker => worker.accepted !== false);
+	const acceptedWorkerBytes = sumWorkerBytes(acceptedWorkers);
+	const acceptedWorkerCount = acceptedWorkers.length;
+	const unmanagedBytes = Math.max(0, totalUsageBytes - parentBytes - acceptedWorkerBytes);
+	const headroomBytes = Math.max(0, effectiveLimitBytes - totalUsageBytes);
+	const workerBudgetBytes = Math.max(0, effectiveLimitBytes - unmanagedBytes - parentReserveBytes);
+	const perWorkerAllowanceBytes = acceptedWorkerCount === 0 ? 0 : workerBudgetBytes / acceptedWorkerCount;
+	const workers: MemoryGuardWorkerAccounting[] = input.workers.map(worker => {
+		const accepted = worker.accepted !== false;
+		return {
+			workerId: worker.workerId,
+			bytes: worker.bytes,
+			accepted,
+			allowanceBytes: accepted ? perWorkerAllowanceBytes : 0,
+			excessBytes: accepted ? Math.max(0, worker.bytes - perWorkerAllowanceBytes) : 0,
+		};
+	});
+	return {
+		effectiveLimitBytes,
+		totalUsageBytes,
+		parentBytes,
+		parentReserveBytes,
+		totalWorkerBytes,
+		acceptedWorkerCount,
+		unmanagedBytes,
+		headroomBytes,
+		workerBudgetBytes,
+		perWorkerAllowanceBytes,
+		hostExcessBytes: Math.max(0, parentBytes - parentReserveBytes),
+		workers,
+	};
+}

package/src/runtime/memory-guard-contract.ts

@@ -0,0 +1,73 @@
+export interface MemoryGuardPolicy {
+	enabled: boolean;
+	checkIntervalMs: number;
+	gcThresholdRatio: number;
+	restartThresholdRatio: number;
+	restartThresholdWindowMs: number;
+	cooldownMs: number;
+	parentReserveBytes: number;
+	policyLimitBytes: number | null;
+}
+
+export interface MemoryGuardWorkerSample {
+	workerId: string;
+	bytes: number;
+	accepted?: boolean;
+}
+
+export interface MemoryGuardWorkerAccounting {
+	workerId: string;
+	bytes: number;
+	accepted: boolean;
+	allowanceBytes: number;
+	excessBytes: number;
+}
+
+export interface MemoryGuardDomainSnapshot {
+	effectiveLimitBytes: number;
+	totalUsageBytes: number;
+	parentBytes: number;
+	parentReserveBytes: number;
+	totalWorkerBytes: number;
+	acceptedWorkerCount: number;
+	unmanagedBytes: number;
+	headroomBytes: number;
+	workerBudgetBytes: number;
+	perWorkerAllowanceBytes: number;
+	hostExcessBytes: number;
+	workers: MemoryGuardWorkerAccounting[];
+}
+
+export interface MemoryGuardHostTarget {
+	kind: "host";
+	excessBytes: number;
+}
+
+export interface MemoryGuardWorkerTarget {
+	kind: "worker";
+	workerId: string;
+	excessBytes: number;
+}
+
+export type MemoryGuardActionTarget = MemoryGuardHostTarget | MemoryGuardWorkerTarget;
+
+export type MemoryGuardNoopReason =
+	| "memory_guard_action_noop_unmanaged_or_within_allowance"
+	| "memory_guard_action_noop_unsupported";
+
+export type MemoryGuardDecision =
+	| { kind: "execute"; target: MemoryGuardActionTarget }
+	| { kind: "noop"; reason: MemoryGuardNoopReason }
+	| { kind: "revalidated_out"; reason: "memory_guard_action_revalidated_out" };
+
+export interface MemoryGuardSchedulerState {
+	timerActive: boolean;
+	registrationCount: number;
+	inProgress: boolean;
+	generation: number;
+	pendingDeadline: number | null;
+	pendingOwner: { generation: number; token: number } | null;
+	deferredDeadline: number | null;
+	deferredGeneration: number | null;
+	activeGeneration: number | null;
+}

package/src/runtime/memory-guard.ts

@@ -0,0 +1,292 @@
+import type { Settings } from "../config/settings";
+import type {
+	MemoryGuardActionTarget,
+	MemoryGuardDecision,
+	MemoryGuardDomainSnapshot,
+	MemoryGuardPolicy,
+	MemoryGuardSchedulerState,
+} from "./memory-guard-contract";
+
+const BYTES_PER_MB = 1024 * 1024;
+const DEFAULT_CHECK_INTERVAL_MS = 30_000;
+
+type ScheduleOwner = { generation: number; token: number };
+type DeferredSchedule = { generation: number; deadline: number };
+type WorkOwner = { generation: number; source: "timer" | "external" };
+
+export interface MemoryGuardHostRegistration {
+	ownerId: string;
+	intervalMs: number;
+}
+
+export interface MemoryGuardHostOptions {
+	run: () => Promise<void>;
+	logDebug?: (message: string, meta?: Record<string, unknown>) => void;
+	schedulerNow?: () => number;
+}
+
+function normalizePositiveIntervalMs(intervalMs: number): number {
+	if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("invalid_interval_ms");
+	return intervalMs;
+}
+
+function toRatio(percent: number): number {
+	return percent / 100;
+}
+
+function mbToBytes(value: number): number {
+	return Math.round(value * BYTES_PER_MB);
+}
+
+function sortTargets(left: MemoryGuardActionTarget, right: MemoryGuardActionTarget): number {
+	if (left.excessBytes !== right.excessBytes) return right.excessBytes - left.excessBytes;
+	if (left.kind !== right.kind) return left.kind === "host" ? -1 : 1;
+	if (left.kind === "worker" && right.kind === "worker") return left.workerId.localeCompare(right.workerId);
+	return 0;
+}
+
+export function resolveMemoryGuardPolicy(settings: Settings): MemoryGuardPolicy {
+	const configuredPolicyLimitMb = settings.get("memoryGuard.policyLimitMb");
+	return {
+		enabled: settings.get("memoryGuard.enabled"),
+		checkIntervalMs: settings.get("memoryGuard.checkIntervalMs"),
+		gcThresholdRatio: toRatio(settings.get("memoryGuard.gcThresholdPercent")),
+		restartThresholdRatio: toRatio(settings.get("memoryGuard.restartThresholdPercent")),
+		restartThresholdWindowMs: settings.get("memoryGuard.restartThresholdWindowMs"),
+		cooldownMs: settings.get("memoryGuard.cooldownMs"),
+		parentReserveBytes: mbToBytes(settings.get("memoryGuard.parentReserveMb")),
+		policyLimitBytes: configuredPolicyLimitMb > 0 ? mbToBytes(configuredPolicyLimitMb) : null,
+	};
+}
+
+export function chooseMemoryGuardAction(input: {
+	domain: MemoryGuardDomainSnapshot;
+	hostSupported: boolean;
+	workerSupported: (workerId: string) => boolean;
+}): MemoryGuardDecision {
+	const candidates: MemoryGuardActionTarget[] = [];
+	if (input.hostSupported && input.domain.hostExcessBytes > 0) {
+		candidates.push({ kind: "host", excessBytes: input.domain.hostExcessBytes });
+	}
+	for (const worker of input.domain.workers) {
+		if (!worker.accepted || worker.excessBytes <= 0 || !input.workerSupported(worker.workerId)) continue;
+		candidates.push({ kind: "worker", workerId: worker.workerId, excessBytes: worker.excessBytes });
+	}
+	if (candidates.length > 0) {
+		candidates.sort(sortTargets);
+		return { kind: "execute", target: candidates[0]! };
+	}
+	const unsupportedExcessExists =
+		input.domain.hostExcessBytes > 0 ||
+		input.domain.workers.some(worker => worker.accepted && worker.excessBytes > 0);
+	if (unsupportedExcessExists) return { kind: "noop", reason: "memory_guard_action_noop_unsupported" };
+	return { kind: "noop", reason: "memory_guard_action_noop_unmanaged_or_within_allowance" };
+}
+
+export function revalidateMemoryGuardAction(
+	previous: Extract<MemoryGuardDecision, { kind: "execute" }>,
+	revalidated: MemoryGuardDecision,
+): MemoryGuardDecision {
+	if (revalidated.kind !== "execute")
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	if (previous.target.kind !== revalidated.target.kind)
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	if (
+		previous.target.kind === "worker" &&
+		revalidated.target.kind === "worker" &&
+		previous.target.workerId !== revalidated.target.workerId
+	) {
+		return { kind: "revalidated_out", reason: "memory_guard_action_revalidated_out" };
+	}
+	return revalidated;
+}
+
+export class MemoryGuardHost {
+	#run: () => Promise<void>;
+	#logDebug: (message: string, meta?: Record<string, unknown>) => void;
+	#defaultSchedulerNow: () => number;
+	#schedulerNow: () => number;
+	#registrations = new Map<string, { intervalMs: number; nextDueMs: number }>();
+	#pendingTimer: NodeJS.Timeout | null = null;
+	#pendingDeadline: number | null = null;
+	#pendingOwner: ScheduleOwner | null = null;
+	#deferredSchedule: DeferredSchedule | null = null;
+	#inProgressOwner: WorkOwner | null = null;
+	#stopped = false;
+	#generation = 0;
+	#nextTimerToken = 0;
+
+	constructor(options: MemoryGuardHostOptions) {
+		this.#run = options.run;
+		this.#logDebug = options.logDebug ?? (() => undefined);
+		this.#defaultSchedulerNow = options.schedulerNow ?? (() => performance.now());
+		this.#schedulerNow = this.#defaultSchedulerNow;
+	}
+
+	register(registration: MemoryGuardHostRegistration): () => void {
+		const intervalMs = normalizePositiveIntervalMs(registration.intervalMs);
+		const now = this.#schedulerNow();
+		const existing = this.#registrations.get(registration.ownerId);
+		const isNewRegistration = !existing;
+		const nextDueMs = existing ? Math.min(existing.nextDueMs, now + intervalMs) : now + intervalMs;
+		this.#registrations.set(registration.ownerId, { intervalMs, nextDueMs });
+		this.#stopped = false;
+		if (isNewRegistration) {
+			const deadline = nextDueMs;
+			if (
+				this.#inProgressOwner?.generation === this.#generation &&
+				(this.#pendingDeadline === null || this.#pendingDeadline <= deadline)
+			) {
+				this.#deferSchedule(this.#generation, deadline);
+			} else {
+				this.#requestSchedule(deadline);
+			}
+		}
+		let unregistered = false;
+		return () => {
+			if (unregistered) return;
+			unregistered = true;
+			this.#registrations.delete(registration.ownerId);
+			if (this.#registrations.size === 0) this.#stop();
+		};
+	}
+
+	updateInterval(ownerId: string, intervalMs: number): void {
+		const existing = this.#registrations.get(ownerId);
+		if (!existing) return;
+		const normalized = normalizePositiveIntervalMs(intervalMs);
+		if (existing.intervalMs === normalized) return;
+		const now = this.#schedulerNow();
+		const nextDueMs = now + normalized;
+		this.#registrations.set(ownerId, { intervalMs: normalized, nextDueMs });
+		if (this.#inProgressOwner) return;
+		const nextDeadline = this.#nextDeadlineMs();
+		if (this.#pendingDeadline !== null && nextDeadline > this.#pendingDeadline) {
+			this.#clearPendingSchedule();
+		}
+		this.#requestSchedule(nextDeadline);
+	}
+
+	async runTick(generation = this.#generation, source: WorkOwner["source"] = "external"): Promise<void> {
+		if (this.#inProgressOwner || this.#registrations.size === 0) return;
+		const owner: WorkOwner = { generation, source };
+		this.#inProgressOwner = owner;
+		try {
+			await this.#run();
+		} catch (error) {
+			this.#logDebug("memory guard tick failed", { error: error instanceof Error ? error.message : String(error) });
+		} finally {
+			if (this.#inProgressOwner === owner) this.#inProgressOwner = null;
+			this.#advanceDueTimes();
+			this.#reconcileCurrentSchedule();
+		}
+	}
+
+	async runTimerCallbackForTest(owner: { generation: number; token: number }, deadline: number): Promise<void> {
+		await this.#handleTimerCallback(owner, deadline);
+	}
+
+	setSchedulerNowForTest(now: () => number): void {
+		this.#schedulerNow = now;
+	}
+
+	getStateForTest(): MemoryGuardSchedulerState {
+		return {
+			timerActive: this.#pendingTimer !== null,
+			registrationCount: this.#registrations.size,
+			inProgress: this.#inProgressOwner !== null,
+			generation: this.#generation,
+			pendingDeadline: this.#pendingDeadline,
+			pendingOwner: this.#pendingOwner ? { ...this.#pendingOwner } : null,
+			deferredDeadline: this.#deferredSchedule?.deadline ?? null,
+			deferredGeneration: this.#deferredSchedule?.generation ?? null,
+			activeGeneration: this.#inProgressOwner?.generation ?? null,
+		};
+	}
+
+	resetForTest(): void {
+		this.#stop();
+		this.#registrations.clear();
+		this.#inProgressOwner = null;
+		this.#deferredSchedule = null;
+		this.#nextTimerToken = 0;
+		this.#schedulerNow = this.#defaultSchedulerNow;
+	}
+
+	#nextDeadlineMs(): number {
+		let minDue = Number.POSITIVE_INFINITY;
+		for (const reg of this.#registrations.values()) {
+			minDue = Math.min(minDue, reg.nextDueMs);
+		}
+		return Number.isFinite(minDue) ? minDue : this.#schedulerNow() + DEFAULT_CHECK_INTERVAL_MS;
+	}
+
+	#advanceDueTimes(): void {
+		const now = this.#schedulerNow();
+		for (const reg of this.#registrations.values()) {
+			if (reg.nextDueMs <= now) {
+				reg.nextDueMs = now + reg.intervalMs;
+			}
+		}
+	}
+
+	#clearPendingSchedule(): void {
+		if (this.#pendingTimer) clearTimeout(this.#pendingTimer);
+		this.#pendingTimer = null;
+		this.#pendingDeadline = null;
+		this.#pendingOwner = null;
+	}
+
+	#requestSchedule(deadline: number): void {
+		if (this.#stopped || this.#registrations.size === 0) return;
+		if (this.#pendingDeadline !== null && this.#pendingDeadline <= deadline) return;
+		this.#clearPendingSchedule();
+		const owner = { generation: this.#generation, token: ++this.#nextTimerToken };
+		this.#pendingDeadline = deadline;
+		this.#pendingOwner = owner;
+		this.#pendingTimer = setTimeout(
+			() => {
+				void this.#handleTimerCallback(owner, deadline);
+			},
+			Math.max(0, deadline - this.#schedulerNow()),
+		);
+		this.#pendingTimer.unref?.();
+	}
+
+	#deferSchedule(generation: number, deadline: number): void {
+		if (generation !== this.#generation) return;
+		if (this.#deferredSchedule?.generation === generation) {
+			this.#deferredSchedule.deadline = Math.min(this.#deferredSchedule.deadline, deadline);
+			return;
+		}
+		this.#deferredSchedule = { generation, deadline };
+	}
+
+	async #handleTimerCallback(owner: ScheduleOwner, deadline: number): Promise<void> {
+		if (this.#pendingOwner?.generation !== owner.generation || this.#pendingOwner.token !== owner.token) return;
+		this.#pendingTimer = null;
+		this.#pendingDeadline = null;
+		this.#pendingOwner = null;
+		if (this.#inProgressOwner) {
+			this.#deferSchedule(owner.generation, deadline);
+			return;
+		}
+		await this.runTick(owner.generation, "timer");
+	}
+
+	#reconcileCurrentSchedule(): void {
+		if (this.#stopped || this.#registrations.size === 0 || this.#inProgressOwner) return;
+		const normalDeadline = this.#nextDeadlineMs();
+		const deferredDeadline =
+			this.#deferredSchedule?.generation === this.#generation ? this.#deferredSchedule.deadline : null;
+		if (deferredDeadline !== null) this.#deferredSchedule = null;
+		this.#requestSchedule(deferredDeadline === null ? normalDeadline : Math.min(deferredDeadline, normalDeadline));
+	}
+
+	#stop(): void {
+		this.#stopped = true;
+		this.#generation++;
+		this.#clearPendingSchedule();
+		this.#deferredSchedule = null;
+	}
+}

package/src/runtime/memory-limit.ts

@@ -0,0 +1,50 @@
+export interface EffectiveMemoryLimitInput {
+	hardCapBytes?: number | null;
+	policyLimitBytes?: number | null;
+}
+
+export interface EffectiveMemoryLimit {
+	hardCapBytes: number | null;
+	policyLimitBytes: number | null;
+	effectiveBytes: number | null;
+	source: "none" | "hard_cap" | "policy_limit" | "hard_cap_and_policy_limit";
+}
+
+function normalizePositiveByteCount(value: number | null | undefined): number | null {
+	return Number.isSafeInteger(value) && typeof value === "number" && value > 0 ? value : null;
+}
+
+export function resolveEffectiveMemoryLimit(input: EffectiveMemoryLimitInput): EffectiveMemoryLimit {
+	const hardCapBytes = normalizePositiveByteCount(input.hardCapBytes);
+	const policyLimitBytes = normalizePositiveByteCount(input.policyLimitBytes);
+	if (hardCapBytes !== null && policyLimitBytes !== null) {
+		return {
+			hardCapBytes,
+			policyLimitBytes,
+			effectiveBytes: Math.min(hardCapBytes, policyLimitBytes),
+			source: "hard_cap_and_policy_limit",
+		};
+	}
+	if (hardCapBytes !== null) {
+		return {
+			hardCapBytes,
+			policyLimitBytes: null,
+			effectiveBytes: hardCapBytes,
+			source: "hard_cap",
+		};
+	}
+	if (policyLimitBytes !== null) {
+		return {
+			hardCapBytes: null,
+			policyLimitBytes,
+			effectiveBytes: policyLimitBytes,
+			source: "policy_limit",
+		};
+	}
+	return {
+		hardCapBytes: null,
+		policyLimitBytes: null,
+		effectiveBytes: null,
+		source: "none",
+	};
+}