@sayknow-cli/coding-agent 0.4.6 → 0.5.0

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

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@sayknow-cli/agent-core";
 import type { AssistantMessage, ImageContent, Message } from "@sayknow-cli/ai";
-import { type Component, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@sayknow-cli/tui";
+import { type Component, Loader, Spacer, Text, TruncatedText, type TUI, truncateToWidth } from "@sayknow-cli/tui";
 import { settings } from "../../config/settings";
 import { resolveSubskillActivationForSkillInvocation } from "../../extensibility/skc-plugins";
 import { buildSkillPromptMessage, parseSkillInvocations } from "../../extensibility/skills";
@@ -86,6 +86,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;
@@ -922,9 +1015,11 @@ export class UiHelpers {
 				const queuedText = theme.fg("dim", `${entry.label}: ${entry.message}`);
 				this.ctx.pendingMessagesContainer.addChild(new TruncatedText(queuedText, 1, 0));
 			}
-			const dequeueKey = this.ctx.keybindings.getDisplayString("app.message.dequeue") || "Alt+Up/Alt+Down";
-			const hintText = theme.fg("dim", `${theme.tree.hook} ${dequeueKey} to select/edit/reorder`);
-			this.ctx.pendingMessagesContainer.addChild(new TruncatedText(hintText, 1, 0));
+			const dequeueKey = this.ctx.keybindings.getDisplayString("app.message.dequeue");
+			if (dequeueKey) {
+				const hintText = theme.fg("dim", `${theme.tree.hook} ${dequeueKey} to select/edit/reorder`);
+				this.ctx.pendingMessagesContainer.addChild(new TruncatedText(hintText, 1, 0));
+			}
 		}
 	}
 

package/src/prompts/agent-fragments/restricted-bash.md

@@ -1 +1 @@
-- Exception: restricted `bash` is only for sanctioned SKC workflow persistence (`skc ralplan --write ...`) and SKC workflow state commands (`skc state ...`). Pass artifacts through `SKC_RALPLAN_ARTIFACT` with `--artifact-env SKC_RALPLAN_ARTIFACT`; never use bash for product-source writes or general shell work.
+- Exception: restricted `bash` is only for sanctioned SKC workflow persistence (`skc ralplan --write ...`), SKC workflow state commands (`skc state ...`), and read-only git inspection (`git status`, `git log`, `git show`, `git diff`, `git blame`, `git rev-parse`, `git ls-files`). Pass artifacts through `SKC_RALPLAN_ARTIFACT` with `--artifact-env SKC_RALPLAN_ARTIFACT`; never use bash for product-source writes, commits, pushes, or other mutating/general shell work.

package/src/prompts/agents/architect.md

@@ -1,13 +1,20 @@
 ---
 name: architect
 description: Read-only architecture and code-review agent with severity-rated findings and status verdicts
-tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding
+tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding, irc
 thinking-level: high
 blocking: true
 forkContext: allowed
 bashAllowedPrefixes:
   - skc ralplan --write
   - skc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Architect. You combine system architecture review with code-review discipline. Diagnose, analyze, and recommend with file-backed evidence. You are read-only.
@@ -30,12 +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.
-- Practical sufficiency beats endless logical completeness: treat preemptive logic for edge cases with no observed or evidenced trigger as over-engineering, but never downgrade genuine CRITICAL/HIGH architecture, extensibility, or robustness risks that have observability-based evidence.
 </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

@@ -1,11 +1,18 @@
 ---
 name: critic
 description: Read-only plan critic that approves only actionable, verifiable execution plans
-tools: read, search, find, lsp, ast_grep, web_search, bash
+tools: read, search, find, lsp, ast_grep, web_search, bash, irc
 thinking-level: high
 bashAllowedPrefixes:
   - skc ralplan --write
   - skc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Critic. Decide whether a work plan is actionable before execution begins.
@@ -23,9 +30,17 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Do not invent problems; report no issues found when the plan passes.
 - Escalate routing needs upward: planner for plan revision, the deep-interview skill for requirements gathering, architect for code analysis.
 - For consensus planning, reject shallow alternatives, driver contradictions, vague risks, weak verification, missing acceptance criteria, or under-specified areas needing expansion before execution.
-- Prefer practical sufficiency over endless logical completeness: do not demand preemptive logic for edge cases that are not actually observed or evidenced, yet still require extensibility and robustness when observability-based evidence shows the investment is worth the token and time.
 </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/agents/planner.md

@@ -1,11 +1,18 @@
 ---
 name: planner
 description: Read-only planning agent for sequencing, acceptance criteria, risks, and handoff shape
-tools: read, search, find, lsp, ast_grep, web_search, bash
+tools: read, search, find, lsp, ast_grep, web_search, bash, irc
 thinking-level: medium
 bashAllowedPrefixes:
   - skc ralplan --write
   - skc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Planner. Turn requests into actionable work plans. You plan; you do not implement.

package/src/prompts/system/btw-user.md

@@ -1,8 +1,3 @@
-<btw>
-This is an ephemeral side question for the current interactive session.
-Answer briefly and directly using the conversation context already provided.
-Do not use tools.
-Do not ask follow-up questions.
-Question:
-{{question}}
-</btw>
+You are answering inside an ephemeral multi-turn side chat for the interactive session.
+Use only the sanitized visible-text conversation scope and prior side-chat turns provided as messages.
+Answer directly. Do not use tools or request hidden session state.

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

@@ -0,0 +1,32 @@
+[SUGGESTION MODE: Suggest what the user might naturally type next into the coding agent.]
+
+FIRST: Look at the user's recent messages and original request.
+
+Your job is to predict what THEY would type - not what you think they should do.
+
+THE TEST: Would they think "I was just about to type that"?
+
+EXAMPLES:
+User asked "fix the bug and run tests", bug is fixed → "run the tests"
+After code written → "try it out"
+Agent offers options → suggest the one the user would likely pick, based on conversation
+Agent asks to continue → "yes" or "go ahead"
+Task complete, obvious follow-up → "commit this" or "push it"
+After error or misunderstanding → silence (let them assess/correct)
+
+Be specific: "run the tests" beats "continue".
+
+NEVER SUGGEST:
+- Evaluative ("looks good", "thanks")
+- Questions ("what about…?")
+- Agent-voice ("Let me…", "I'll…", "Here's…")
+- New ideas they didn't ask about
+- Multiple sentences
+
+Stay silent if the next step isn't obvious from what the user said.
+
+Stay silent if a suggestion could be unsafe or inappropriate — including any sensitive topic (security incidents, credentials, harm, private data). Even when the user is doing legitimate security or cybersecurity work, do not predict potentially unsafe actions.
+
+Format: 2-12 words, match the user's style. Or nothing.
+
+Reply with ONLY the suggestion, no quotes or explanation.

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

@@ -19,12 +19,15 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 {{#unless subagent}}
 <skc-runtime>
 <routing>
-- Clear, low-risk implementation requests use direct tools and focused verification; do not invoke workflows or role agents for ceremony.
+- Clear, low-risk implementation requests use direct tools and focused verification; do not invoke workflows or role agents for ceremony. Small verification needs do not turn a clear request into a planning workflow.
+- Ambiguous implementation asks with a missing target, scope, acceptance criteria, or safety boundary require clarification or the appropriate planning workflow before mutation.
 - Informational questions are answer-only/read-only unless the user explicitly requests a change, command, or execution.
-- Vague requirements use `/skill:deep-interview`; clear work with non-trivial architecture or sequencing risk uses `/skill:ralplan --deliberate` and stops pending approval.
+- 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.
 - 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: read and follow them; planning and read-only skills do not mutate before approval.
+- Active skills are authoritative: never ignore an invoked skill; read the full skill text and follow it exactly.
+- Before explicit execution approval, planning and interview workflows NEVER edit product source, run mutating shell commands, commit, push, open PRs, or delegate implementation.
 </routing>
 </skc-runtime>
 {{/unless}}

package/src/prompts/tools/cron.md

@@ -1,4 +1,6 @@
-Schedule a prompt to fire on a recurring cron schedule, or one-shot at the next match. Cron tasks let you re-run a prompt automatically on an interval — poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
+Schedule a prompt to fire on a recurring cron schedule, or one-shot at the next match. Cron tasks re-run an agent prompt automatically on an interval when every firing is allowed to produce a normal assistant response, such as a reminder or a scheduled status report.
+
+Cron is not a silent polling primitive. Every firing starts an agent turn, and hiding the injected cron message does not hide that turn's assistant response. For ongoing logs, file watching, or PR/CI polling that should report only meaningful state changes, use `monitor` with a script that writes a line only when there is an event to process, and set `persistent: true` so the monitor survives the first emitted event. Do not schedule a cron prompt that asks the agent to suppress routine polls; prompt wording cannot make a cron-triggered assistant turn reliably silent.
 
 Use a single `op` field to select the operation:
 

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/prompts/tools/skill-discovery.md

@@ -3,6 +3,7 @@ Discover project and user runtime skills without loading full skill content.
 <instruction>
 - Searches only custom runtime skill locations: nearest project `.skc/skills`; then, under the home directory, canonical `<config>/agent/skills`, configured legacy `<config>/skills`, and historical legacy `.skc/skills`. `<config>` is the home-relative directory name from `SKC_CONFIG_DIR`, then `PI_CONFIG_DIR`, then `.skc`; even an absolute-looking configured name is joined beneath `<home>`. Duplicate names use that exact precedence. Built-in, bundled, and internal workflow skills are intentionally excluded.
 - Returns thin metadata only: name, description, source scope, path, and use conditions when present.
+- When zero candidates are returned because discovery config is disabled (`skills.enabled`, `skills.enablePiProject`, `skills.enablePiUser`), the result carries a `notice` explaining which setting blocked the search — an empty result without a `notice` means the searched scopes genuinely contain no matching skills.
 - To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.
 </instruction>
 

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;
+}