context-brake 1.0.0 → 1.1.0

package/dist/assets/runtime/omp-extension.js

@@ -4,6 +4,14 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/services/skill-invocation.ts
+function sentenceInvocation(skill) {
+  return `use the ${skill} skill`;
+}
+
+// src/infrastructure/harnesses/oh-my-pi/skill-invocation.ts
+var OMP_SKILL_INVOCATION = sentenceInvocation;
+
 // node_modules/zod/v4/mini/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -18155,6 +18163,34 @@ var HARNESS_IDS = [
   "antigravity-cli"
 ];
 
+// src/core/contracts/skill-name.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var NAME_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+var NAMESPACE_SEPARATOR = ":";
+var INVOCATION_CHARACTERS = ["/", "$", "@"];
+var MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+  return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+var PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+var SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits("$")}${NAME_SEGMENT}$`);
+var SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+function isSkillName(value) {
+  return SKILL_NAME_PATTERN.test(value);
+}
+function skillNameProblem(value) {
+  if (value === "") return "must not be empty";
+  if (isSkillName(value)) return null;
+  const bare = INVOCATION_CHARACTERS.includes(value.charAt(0)) ? value.slice(1) : null;
+  if (bare !== null && isSkillName(bare)) return `"${value}" is not a skill name; use the bare name ${bare}`;
+  return `"${value}" is not a skill name; use ${SHAPE_RULE}`;
+}
+var skillNameSchema = external_exports.string().check((ctx) => {
+  const message = skillNameProblem(ctx.value);
+  if (message !== null) ctx.issues.push({ code: "custom", input: ctx.value, message });
+});
+external_exports.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });
+
 // src/core/contracts/zones.ts
 var ZONES = ["GREEN", "YELLOW", "RED", "CRITICAL"];
 var USAGE_SOURCES = ["measured", "estimated"];
@@ -18178,15 +18214,8 @@ function uniqueCheck(message) {
     if (!isUnique(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message });
   };
 }
-var MAX_AGENT_COMMAND_LENGTH = 200;
-var TRIMMED_RULE = "must not have leading or trailing whitespace";
 var RESUME_REQUIRES_COMMAND_RULE = "requires snapshot.command";
-var SINGLE_LINE_RULE = "must be a single line";
-var agentCommand = external_exports.string().check(external_exports.minLength(1), external_exports.maxLength(MAX_AGENT_COMMAND_LENGTH), (ctx) => {
-  if (ctx.value.trim() !== ctx.value) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: TRIMMED_RULE });
-  if (/[\r\n]/.test(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: SINGLE_LINE_RULE });
-});
-var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), command: external_exports.optional(agentCommand), resumeCommand: external_exports.optional(agentCommand) }).check((ctx) => {
+var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), triggerPercentage: external_exports.optional(external_exports.int().check(external_exports.minimum(1), external_exports.maximum(100))), command: external_exports.optional(skillNameSchema), resumeCommand: external_exports.optional(skillNameSchema) }).check((ctx) => {
   if (ctx.value.resumeCommand !== void 0 && ctx.value.command === void 0) addIssue(ctx, { code: "custom", path: ["resumeCommand"], input: ctx.value.resumeCommand, message: RESUME_REQUIRES_COMMAND_RULE });
 });
 var DEFAULT_SNAPSHOT = { triggerZone: "RED" };
@@ -18267,21 +18296,25 @@ var GENERIC_ACTIONS = {
   RED: "finish or pause the current unit and tell the user what remains",
   CRITICAL: "stop starting new work; tell the user what remains"
 };
-function zoneAction(zone, snapshot, mode = "off") {
-  if (zone === "GREEN" || !isAtOrAbove(zone, snapshot.triggerZone)) return GENERIC_ACTIONS[zone];
-  if (snapshot.command !== void 0) return snapshotAction(zone, snapshot.command);
-  if (mode !== "handoff") return GENERIC_ACTIONS[zone];
+function isResetDue(reading, snapshot) {
+  if (snapshot.triggerPercentage !== void 0) return reading.usagePercentage >= snapshot.triggerPercentage;
+  return reading.zone !== "GREEN" && isAtOrAbove(reading.zone, snapshot.triggerZone);
+}
+function zoneAction(zone, snapshot, options = {}) {
+  if (!isResetDue({ zone, usagePercentage: options.usagePercentage ?? 0 }, snapshot)) return GENERIC_ACTIONS[zone];
+  if (snapshot.command !== void 0) return snapshotAction(zone, (options.invoke ?? sentenceInvocation)(snapshot.command));
+  if ((options.mode ?? "off") !== "handoff") return GENERIC_ACTIONS[zone];
   return `save handoff to ${HANDOFF_PATH}, end reply with ${SESSION_RESET_SIGNAL}`;
 }
-function snapshotAction(zone, command) {
+function snapshotAction(zone, invocation) {
   const now = zone === "CRITICAL" ? " now" : "";
-  return `run "${command}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
+  return `run "${invocation}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
 }
 function handoffResumeText(archivedPath) {
   return `${RESUME_PREFIX} Read "${archivedPath}" and continue the previous work from it.`;
 }
-function resumeText(snapshot) {
-  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${snapshot.resumeCommand}" before continuing.`;
+function resumeText(snapshot, invoke = sentenceInvocation) {
+  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${invoke(snapshot.resumeCommand)}" before continuing.`;
 }
 function isAtOrAbove(zone, trigger) {
   return ZONES.indexOf(zone) >= ZONES.indexOf(trigger);
@@ -18326,7 +18359,7 @@ async function resolveFailure(input2) {
   return { kind: "neutral" };
 }
 function deadlineBootDecision(input2) {
-  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot);
+  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot, input2.descriptor?.skillInvocation);
   return text === null ? { kind: "neutral" } : { kind: "context", block: text };
 }
 async function recordRuntimeFailure(errors, record2) {
@@ -18474,7 +18507,20 @@ async function listRuntimeStateFiles(root, readdirFn = readdir) {
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
-var RUNTIME_GITIGNORE_CONTENT = "*\n";
+
+// src/core/contracts/context-reading.ts
+var RUNTIME_IGNORE_CONTENT = "*\n";
+var PERCENTAGE_MAXIMUM = 100;
+var contextReadingSchema = external_exports.strictObject({
+  v: external_exports.literal(1),
+  at: external_exports.string().check(external_exports.minLength(1)),
+  windowTokens: external_exports.nullable(external_exports.int().check(external_exports.positive())),
+  inputTokens: external_exports.nullable(external_exports.int().check(external_exports.nonnegative())),
+  usedPercentage: external_exports.nullable(external_exports.number().check(external_exports.gte(0), external_exports.lte(PERCENTAGE_MAXIMUM)))
+});
+
+// src/infrastructure/runtime/runtime-paths.ts
+var RUNTIME_GITIGNORE_CONTENT = RUNTIME_IGNORE_CONTENT;
 var SESSIONS_DIR_NAME = "sessions";
 var LEDGER_FILE_EXTENSION = ".jsonl";
 var SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
@@ -18582,7 +18628,7 @@ function isDebugModeInEffect(config2) {
 
 // src/core/services/injection-policy.ts
 function decideInjection(input2) {
-  if (input2.debug || input2.telemetry.injectionMode === "always") return true;
+  if (input2.debug || input2.resetDue === true || input2.telemetry.injectionMode === "always") return true;
   return input2.zone !== "GREEN" || input2.usagePercentage >= input2.telemetry.activationThresholdPercentage;
 }
 
@@ -18733,7 +18779,7 @@ async function handleSessionReset(options, event, hooks = {}) {
   if (!options.descriptor.capabilities.some((entry) => entry.id === "session_boot" && entry.state === "supported")) return NEUTRAL;
   if (event.reason === "compact" && !COMPACTION_BOOT_HARNESSES.includes(options.descriptor.harness)) return NEUTRAL;
   hooks.onPhase?.("guidance");
-  const text = resumeText(options.config.snapshot) ?? await claimHandoff(options, event.reason, hooks.deadline);
+  const text = resumeText(options.config.snapshot, options.descriptor.skillInvocation) ?? await claimHandoff(options, event.reason, hooks.deadline);
   return text === null ? NEUTRAL : { kind: "context", block: text };
 }
 async function claimHandoff(options, reason, deadline) {
@@ -18775,8 +18821,9 @@ async function handlePreInvocation(options, event, input2) {
   return telemetryDecision(options, summary.turns, readZone(options, { summary, turns: summary.turns, observedCharacters: 0, measured: input2.measured }));
 }
 async function telemetryDecision(options, turn, view) {
-  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config) })) return NEUTRAL2;
-  const action = zoneAction(view.zone, options.config.snapshot, restartMode(options.config));
+  const resetDue = isResetDue({ zone: view.zone, usagePercentage: view.percentage }, options.config.snapshot);
+  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config), resetDue })) return NEUTRAL2;
+  const action = zoneAction(view.zone, options.config.snapshot, { mode: restartMode(options.config), invoke: options.descriptor.skillInvocation, usagePercentage: view.percentage });
   return { kind: "context", block: renderTelemetryBlock({ turn, turnCeiling: redStartTurn(options.config.telemetry.zones), usagePercentage: view.percentage, usage: view.reading, zone: view.zone, action, debug: isDebugModeInEffect(options.config) }) };
 }
 async function handleResponseEnd(options, event) {
@@ -19173,7 +19220,7 @@ function renderOmpToolResult(payload, block) {
 // src/infrastructure/harnesses/oh-my-pi/runtime.ts
 var HARNESS = "oh-my-pi";
 var ESTIMATION = { baselineTokens: 15e3, tokensPerTurn: 150 };
-var ompDescriptor = { harness: HARNESS, capabilities: OMP_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: "/new" };
+var ompDescriptor = { harness: HARNESS, capabilities: OMP_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: "/new", skillInvocation: OMP_SKILL_INVOCATION };
 function rootOf(context) {
   return textValue(context.cwd);
 }

package/dist/assets/runtime/omp-restart.js

@@ -18308,6 +18308,34 @@ async function handleTurnEnd(host, turn) {
   });
 }
 
+// src/core/contracts/skill-name.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var NAME_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+var NAMESPACE_SEPARATOR = ":";
+var INVOCATION_CHARACTERS = ["/", "$", "@"];
+var MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+  return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+var PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+var SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits("$")}${NAME_SEGMENT}$`);
+var SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+function isSkillName(value) {
+  return SKILL_NAME_PATTERN.test(value);
+}
+function skillNameProblem(value) {
+  if (value === "") return "must not be empty";
+  if (isSkillName(value)) return null;
+  const bare = INVOCATION_CHARACTERS.includes(value.charAt(0)) ? value.slice(1) : null;
+  if (bare !== null && isSkillName(bare)) return `"${value}" is not a skill name; use the bare name ${bare}`;
+  return `"${value}" is not a skill name; use ${SHAPE_RULE}`;
+}
+var skillNameSchema = external_exports.string().check((ctx) => {
+  const message = skillNameProblem(ctx.value);
+  if (message !== null) ctx.issues.push({ code: "custom", input: ctx.value, message });
+});
+external_exports.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });
+
 // src/core/contracts/zones.ts
 var ZONES = ["GREEN", "YELLOW", "RED", "CRITICAL"];
 var USAGE_SOURCES = ["measured", "estimated"];
@@ -18331,15 +18359,8 @@ function uniqueCheck(message) {
     if (!isUnique(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message });
   };
 }
-var MAX_AGENT_COMMAND_LENGTH = 200;
-var TRIMMED_RULE = "must not have leading or trailing whitespace";
 var RESUME_REQUIRES_COMMAND_RULE = "requires snapshot.command";
-var SINGLE_LINE_RULE = "must be a single line";
-var agentCommand = external_exports.string().check(external_exports.minLength(1), external_exports.maxLength(MAX_AGENT_COMMAND_LENGTH), (ctx) => {
-  if (ctx.value.trim() !== ctx.value) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: TRIMMED_RULE });
-  if (/[\r\n]/.test(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: SINGLE_LINE_RULE });
-});
-var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), command: external_exports.optional(agentCommand), resumeCommand: external_exports.optional(agentCommand) }).check((ctx) => {
+var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), triggerPercentage: external_exports.optional(external_exports.int().check(external_exports.minimum(1), external_exports.maximum(100))), command: external_exports.optional(skillNameSchema), resumeCommand: external_exports.optional(skillNameSchema) }).check((ctx) => {
   if (ctx.value.resumeCommand !== void 0 && ctx.value.command === void 0) addIssue(ctx, { code: "custom", path: ["resumeCommand"], input: ctx.value.resumeCommand, message: RESUME_REQUIRES_COMMAND_RULE });
 });
 var DEFAULT_SNAPSHOT = { triggerZone: "RED" };
@@ -18383,11 +18404,22 @@ var HANDOFF_ARCHIVE_LIMIT = 10;
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
+// src/core/contracts/context-reading.ts
+var RUNTIME_IGNORE_CONTENT = "*\n";
+var PERCENTAGE_MAXIMUM = 100;
+var contextReadingSchema = external_exports.strictObject({
+  v: external_exports.literal(1),
+  at: external_exports.string().check(external_exports.minLength(1)),
+  windowTokens: external_exports.nullable(external_exports.int().check(external_exports.positive())),
+  inputTokens: external_exports.nullable(external_exports.int().check(external_exports.nonnegative())),
+  usedPercentage: external_exports.nullable(external_exports.number().check(external_exports.gte(0), external_exports.lte(PERCENTAGE_MAXIMUM)))
+});
+
 // src/infrastructure/storage/runtime-state-files.ts
 var RUNTIME_STATE_RELATIVE_DIR = ".context-brake/runtime";
 
 // src/infrastructure/runtime/runtime-paths.ts
-var RUNTIME_GITIGNORE_CONTENT = "*\n";
+var RUNTIME_GITIGNORE_CONTENT = RUNTIME_IGNORE_CONTENT;
 var SESSIONS_DIR_NAME = "sessions";
 var SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
 function runtimeDirectory(projectRoot) {

package/dist/assets/runtime/opencode-plugin.js

@@ -4,6 +4,14 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/services/skill-invocation.ts
+function sentenceInvocation(skill) {
+  return `use the ${skill} skill`;
+}
+
+// src/infrastructure/harnesses/opencode/skill-invocation.ts
+var OPENCODE_SKILL_INVOCATION = sentenceInvocation;
+
 // node_modules/zod/v4/mini/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -18155,6 +18163,34 @@ var HARNESS_IDS = [
   "antigravity-cli"
 ];
 
+// src/core/contracts/skill-name.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var NAME_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+var NAMESPACE_SEPARATOR = ":";
+var INVOCATION_CHARACTERS = ["/", "$", "@"];
+var MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+  return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+var PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+var SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits("$")}${NAME_SEGMENT}$`);
+var SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+function isSkillName(value) {
+  return SKILL_NAME_PATTERN.test(value);
+}
+function skillNameProblem(value) {
+  if (value === "") return "must not be empty";
+  if (isSkillName(value)) return null;
+  const bare = INVOCATION_CHARACTERS.includes(value.charAt(0)) ? value.slice(1) : null;
+  if (bare !== null && isSkillName(bare)) return `"${value}" is not a skill name; use the bare name ${bare}`;
+  return `"${value}" is not a skill name; use ${SHAPE_RULE}`;
+}
+var skillNameSchema = external_exports.string().check((ctx) => {
+  const message = skillNameProblem(ctx.value);
+  if (message !== null) ctx.issues.push({ code: "custom", input: ctx.value, message });
+});
+external_exports.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });
+
 // src/core/contracts/zones.ts
 var ZONES = ["GREEN", "YELLOW", "RED", "CRITICAL"];
 var USAGE_SOURCES = ["measured", "estimated"];
@@ -18178,15 +18214,8 @@ function uniqueCheck(message) {
     if (!isUnique(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message });
   };
 }
-var MAX_AGENT_COMMAND_LENGTH = 200;
-var TRIMMED_RULE = "must not have leading or trailing whitespace";
 var RESUME_REQUIRES_COMMAND_RULE = "requires snapshot.command";
-var SINGLE_LINE_RULE = "must be a single line";
-var agentCommand = external_exports.string().check(external_exports.minLength(1), external_exports.maxLength(MAX_AGENT_COMMAND_LENGTH), (ctx) => {
-  if (ctx.value.trim() !== ctx.value) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: TRIMMED_RULE });
-  if (/[\r\n]/.test(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: SINGLE_LINE_RULE });
-});
-var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), command: external_exports.optional(agentCommand), resumeCommand: external_exports.optional(agentCommand) }).check((ctx) => {
+var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), triggerPercentage: external_exports.optional(external_exports.int().check(external_exports.minimum(1), external_exports.maximum(100))), command: external_exports.optional(skillNameSchema), resumeCommand: external_exports.optional(skillNameSchema) }).check((ctx) => {
   if (ctx.value.resumeCommand !== void 0 && ctx.value.command === void 0) addIssue(ctx, { code: "custom", path: ["resumeCommand"], input: ctx.value.resumeCommand, message: RESUME_REQUIRES_COMMAND_RULE });
 });
 var DEFAULT_SNAPSHOT = { triggerZone: "RED" };
@@ -18267,21 +18296,25 @@ var GENERIC_ACTIONS = {
   RED: "finish or pause the current unit and tell the user what remains",
   CRITICAL: "stop starting new work; tell the user what remains"
 };
-function zoneAction(zone, snapshot, mode = "off") {
-  if (zone === "GREEN" || !isAtOrAbove(zone, snapshot.triggerZone)) return GENERIC_ACTIONS[zone];
-  if (snapshot.command !== void 0) return snapshotAction(zone, snapshot.command);
-  if (mode !== "handoff") return GENERIC_ACTIONS[zone];
+function isResetDue(reading, snapshot) {
+  if (snapshot.triggerPercentage !== void 0) return reading.usagePercentage >= snapshot.triggerPercentage;
+  return reading.zone !== "GREEN" && isAtOrAbove(reading.zone, snapshot.triggerZone);
+}
+function zoneAction(zone, snapshot, options = {}) {
+  if (!isResetDue({ zone, usagePercentage: options.usagePercentage ?? 0 }, snapshot)) return GENERIC_ACTIONS[zone];
+  if (snapshot.command !== void 0) return snapshotAction(zone, (options.invoke ?? sentenceInvocation)(snapshot.command));
+  if ((options.mode ?? "off") !== "handoff") return GENERIC_ACTIONS[zone];
   return `save handoff to ${HANDOFF_PATH}, end reply with ${SESSION_RESET_SIGNAL}`;
 }
-function snapshotAction(zone, command) {
+function snapshotAction(zone, invocation) {
   const now = zone === "CRITICAL" ? " now" : "";
-  return `run "${command}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
+  return `run "${invocation}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
 }
 function handoffResumeText(archivedPath) {
   return `${RESUME_PREFIX} Read "${archivedPath}" and continue the previous work from it.`;
 }
-function resumeText(snapshot) {
-  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${snapshot.resumeCommand}" before continuing.`;
+function resumeText(snapshot, invoke = sentenceInvocation) {
+  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${invoke(snapshot.resumeCommand)}" before continuing.`;
 }
 function isAtOrAbove(zone, trigger) {
   return ZONES.indexOf(zone) >= ZONES.indexOf(trigger);
@@ -18326,7 +18359,7 @@ async function resolveFailure(input2) {
   return { kind: "neutral" };
 }
 function deadlineBootDecision(input2) {
-  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot);
+  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot, input2.descriptor?.skillInvocation);
   return text === null ? { kind: "neutral" } : { kind: "context", block: text };
 }
 async function recordRuntimeFailure(errors, record2) {
@@ -18474,7 +18507,20 @@ async function listRuntimeStateFiles(root, readdirFn = readdir) {
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
-var RUNTIME_GITIGNORE_CONTENT = "*\n";
+
+// src/core/contracts/context-reading.ts
+var RUNTIME_IGNORE_CONTENT = "*\n";
+var PERCENTAGE_MAXIMUM = 100;
+var contextReadingSchema = external_exports.strictObject({
+  v: external_exports.literal(1),
+  at: external_exports.string().check(external_exports.minLength(1)),
+  windowTokens: external_exports.nullable(external_exports.int().check(external_exports.positive())),
+  inputTokens: external_exports.nullable(external_exports.int().check(external_exports.nonnegative())),
+  usedPercentage: external_exports.nullable(external_exports.number().check(external_exports.gte(0), external_exports.lte(PERCENTAGE_MAXIMUM)))
+});
+
+// src/infrastructure/runtime/runtime-paths.ts
+var RUNTIME_GITIGNORE_CONTENT = RUNTIME_IGNORE_CONTENT;
 var SESSIONS_DIR_NAME = "sessions";
 var LEDGER_FILE_EXTENSION = ".jsonl";
 var SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
@@ -18582,7 +18628,7 @@ function isDebugModeInEffect(config2) {
 
 // src/core/services/injection-policy.ts
 function decideInjection(input2) {
-  if (input2.debug || input2.telemetry.injectionMode === "always") return true;
+  if (input2.debug || input2.resetDue === true || input2.telemetry.injectionMode === "always") return true;
   return input2.zone !== "GREEN" || input2.usagePercentage >= input2.telemetry.activationThresholdPercentage;
 }
 
@@ -18733,7 +18779,7 @@ async function handleSessionReset(options, event, hooks = {}) {
   if (!options.descriptor.capabilities.some((entry) => entry.id === "session_boot" && entry.state === "supported")) return NEUTRAL;
   if (event.reason === "compact" && !COMPACTION_BOOT_HARNESSES.includes(options.descriptor.harness)) return NEUTRAL;
   hooks.onPhase?.("guidance");
-  const text = resumeText(options.config.snapshot) ?? await claimHandoff(options, event.reason, hooks.deadline);
+  const text = resumeText(options.config.snapshot, options.descriptor.skillInvocation) ?? await claimHandoff(options, event.reason, hooks.deadline);
   return text === null ? NEUTRAL : { kind: "context", block: text };
 }
 async function claimHandoff(options, reason, deadline) {
@@ -18775,8 +18821,9 @@ async function handlePreInvocation(options, event, input2) {
   return telemetryDecision(options, summary.turns, readZone(options, { summary, turns: summary.turns, observedCharacters: 0, measured: input2.measured }));
 }
 async function telemetryDecision(options, turn, view) {
-  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config) })) return NEUTRAL2;
-  const action = zoneAction(view.zone, options.config.snapshot, restartMode(options.config));
+  const resetDue = isResetDue({ zone: view.zone, usagePercentage: view.percentage }, options.config.snapshot);
+  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config), resetDue })) return NEUTRAL2;
+  const action = zoneAction(view.zone, options.config.snapshot, { mode: restartMode(options.config), invoke: options.descriptor.skillInvocation, usagePercentage: view.percentage });
   return { kind: "context", block: renderTelemetryBlock({ turn, turnCeiling: redStartTurn(options.config.telemetry.zones), usagePercentage: view.percentage, usage: view.reading, zone: view.zone, action, debug: isDebugModeInEffect(options.config) }) };
 }
 async function handleResponseEnd(options, event) {
@@ -19151,7 +19198,7 @@ function mapOpenCodeSessionEvent(payload) {
 var HARNESS = "opencode";
 var ESTIMATION = { baselineTokens: 15e3, tokensPerTurn: 150 };
 var FALLBACK_SESSION_ID = "project";
-var openCodeDescriptor = { harness: HARNESS, capabilities: OPENCODE_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: null };
+var openCodeDescriptor = { harness: HARNESS, capabilities: OPENCODE_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: null, skillInvocation: OPENCODE_SKILL_INVOCATION };
 function resolveProjectRoot(context) {
   const record2 = asRecord(context);
   return textValue(record2?.["directory"]) ?? textValue(record2?.["worktree"]) ?? process.cwd();

package/dist/assets/runtime/pi-extension.js

@@ -4,6 +4,17 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/services/skill-invocation.ts
+function skillSlashInvocation(skill) {
+  return `/skill:${skill}`;
+}
+function sentenceInvocation(skill) {
+  return `use the ${skill} skill`;
+}
+
+// src/infrastructure/harnesses/pi/skill-invocation.ts
+var PI_SKILL_INVOCATION = skillSlashInvocation;
+
 // node_modules/zod/v4/mini/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -18155,6 +18166,34 @@ var HARNESS_IDS = [
   "antigravity-cli"
 ];
 
+// src/core/contracts/skill-name.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var NAME_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+var NAMESPACE_SEPARATOR = ":";
+var INVOCATION_CHARACTERS = ["/", "$", "@"];
+var MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+  return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+var PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+var SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits("$")}${NAME_SEGMENT}$`);
+var SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+function isSkillName(value) {
+  return SKILL_NAME_PATTERN.test(value);
+}
+function skillNameProblem(value) {
+  if (value === "") return "must not be empty";
+  if (isSkillName(value)) return null;
+  const bare = INVOCATION_CHARACTERS.includes(value.charAt(0)) ? value.slice(1) : null;
+  if (bare !== null && isSkillName(bare)) return `"${value}" is not a skill name; use the bare name ${bare}`;
+  return `"${value}" is not a skill name; use ${SHAPE_RULE}`;
+}
+var skillNameSchema = external_exports.string().check((ctx) => {
+  const message = skillNameProblem(ctx.value);
+  if (message !== null) ctx.issues.push({ code: "custom", input: ctx.value, message });
+});
+external_exports.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });
+
 // src/core/contracts/zones.ts
 var ZONES = ["GREEN", "YELLOW", "RED", "CRITICAL"];
 var USAGE_SOURCES = ["measured", "estimated"];
@@ -18178,15 +18217,8 @@ function uniqueCheck(message) {
     if (!isUnique(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message });
   };
 }
-var MAX_AGENT_COMMAND_LENGTH = 200;
-var TRIMMED_RULE = "must not have leading or trailing whitespace";
 var RESUME_REQUIRES_COMMAND_RULE = "requires snapshot.command";
-var SINGLE_LINE_RULE = "must be a single line";
-var agentCommand = external_exports.string().check(external_exports.minLength(1), external_exports.maxLength(MAX_AGENT_COMMAND_LENGTH), (ctx) => {
-  if (ctx.value.trim() !== ctx.value) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: TRIMMED_RULE });
-  if (/[\r\n]/.test(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: SINGLE_LINE_RULE });
-});
-var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), command: external_exports.optional(agentCommand), resumeCommand: external_exports.optional(agentCommand) }).check((ctx) => {
+var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), triggerPercentage: external_exports.optional(external_exports.int().check(external_exports.minimum(1), external_exports.maximum(100))), command: external_exports.optional(skillNameSchema), resumeCommand: external_exports.optional(skillNameSchema) }).check((ctx) => {
   if (ctx.value.resumeCommand !== void 0 && ctx.value.command === void 0) addIssue(ctx, { code: "custom", path: ["resumeCommand"], input: ctx.value.resumeCommand, message: RESUME_REQUIRES_COMMAND_RULE });
 });
 var DEFAULT_SNAPSHOT = { triggerZone: "RED" };
@@ -18267,21 +18299,25 @@ var GENERIC_ACTIONS = {
   RED: "finish or pause the current unit and tell the user what remains",
   CRITICAL: "stop starting new work; tell the user what remains"
 };
-function zoneAction(zone, snapshot, mode = "off") {
-  if (zone === "GREEN" || !isAtOrAbove(zone, snapshot.triggerZone)) return GENERIC_ACTIONS[zone];
-  if (snapshot.command !== void 0) return snapshotAction(zone, snapshot.command);
-  if (mode !== "handoff") return GENERIC_ACTIONS[zone];
+function isResetDue(reading, snapshot) {
+  if (snapshot.triggerPercentage !== void 0) return reading.usagePercentage >= snapshot.triggerPercentage;
+  return reading.zone !== "GREEN" && isAtOrAbove(reading.zone, snapshot.triggerZone);
+}
+function zoneAction(zone, snapshot, options = {}) {
+  if (!isResetDue({ zone, usagePercentage: options.usagePercentage ?? 0 }, snapshot)) return GENERIC_ACTIONS[zone];
+  if (snapshot.command !== void 0) return snapshotAction(zone, (options.invoke ?? sentenceInvocation)(snapshot.command));
+  if ((options.mode ?? "off") !== "handoff") return GENERIC_ACTIONS[zone];
   return `save handoff to ${HANDOFF_PATH}, end reply with ${SESSION_RESET_SIGNAL}`;
 }
-function snapshotAction(zone, command) {
+function snapshotAction(zone, invocation) {
   const now = zone === "CRITICAL" ? " now" : "";
-  return `run "${command}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
+  return `run "${invocation}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
 }
 function handoffResumeText(archivedPath) {
   return `${RESUME_PREFIX} Read "${archivedPath}" and continue the previous work from it.`;
 }
-function resumeText(snapshot) {
-  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${snapshot.resumeCommand}" before continuing.`;
+function resumeText(snapshot, invoke = sentenceInvocation) {
+  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${invoke(snapshot.resumeCommand)}" before continuing.`;
 }
 function isAtOrAbove(zone, trigger) {
   return ZONES.indexOf(zone) >= ZONES.indexOf(trigger);
@@ -18326,7 +18362,7 @@ async function resolveFailure(input2) {
   return { kind: "neutral" };
 }
 function deadlineBootDecision(input2) {
-  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot);
+  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot, input2.descriptor?.skillInvocation);
   return text === null ? { kind: "neutral" } : { kind: "context", block: text };
 }
 async function recordRuntimeFailure(errors, record2) {
@@ -18474,7 +18510,20 @@ async function listRuntimeStateFiles(root, readdirFn = readdir) {
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
-var RUNTIME_GITIGNORE_CONTENT = "*\n";
+
+// src/core/contracts/context-reading.ts
+var RUNTIME_IGNORE_CONTENT = "*\n";
+var PERCENTAGE_MAXIMUM = 100;
+var contextReadingSchema = external_exports.strictObject({
+  v: external_exports.literal(1),
+  at: external_exports.string().check(external_exports.minLength(1)),
+  windowTokens: external_exports.nullable(external_exports.int().check(external_exports.positive())),
+  inputTokens: external_exports.nullable(external_exports.int().check(external_exports.nonnegative())),
+  usedPercentage: external_exports.nullable(external_exports.number().check(external_exports.gte(0), external_exports.lte(PERCENTAGE_MAXIMUM)))
+});
+
+// src/infrastructure/runtime/runtime-paths.ts
+var RUNTIME_GITIGNORE_CONTENT = RUNTIME_IGNORE_CONTENT;
 var SESSIONS_DIR_NAME = "sessions";
 var LEDGER_FILE_EXTENSION = ".jsonl";
 var SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
@@ -18582,7 +18631,7 @@ function isDebugModeInEffect(config2) {
 
 // src/core/services/injection-policy.ts
 function decideInjection(input2) {
-  if (input2.debug || input2.telemetry.injectionMode === "always") return true;
+  if (input2.debug || input2.resetDue === true || input2.telemetry.injectionMode === "always") return true;
   return input2.zone !== "GREEN" || input2.usagePercentage >= input2.telemetry.activationThresholdPercentage;
 }
 
@@ -18733,7 +18782,7 @@ async function handleSessionReset(options, event, hooks = {}) {
   if (!options.descriptor.capabilities.some((entry) => entry.id === "session_boot" && entry.state === "supported")) return NEUTRAL;
   if (event.reason === "compact" && !COMPACTION_BOOT_HARNESSES.includes(options.descriptor.harness)) return NEUTRAL;
   hooks.onPhase?.("guidance");
-  const text = resumeText(options.config.snapshot) ?? await claimHandoff(options, event.reason, hooks.deadline);
+  const text = resumeText(options.config.snapshot, options.descriptor.skillInvocation) ?? await claimHandoff(options, event.reason, hooks.deadline);
   return text === null ? NEUTRAL : { kind: "context", block: text };
 }
 async function claimHandoff(options, reason, deadline) {
@@ -18775,8 +18824,9 @@ async function handlePreInvocation(options, event, input2) {
   return telemetryDecision(options, summary.turns, readZone(options, { summary, turns: summary.turns, observedCharacters: 0, measured: input2.measured }));
 }
 async function telemetryDecision(options, turn, view) {
-  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config) })) return NEUTRAL2;
-  const action = zoneAction(view.zone, options.config.snapshot, restartMode(options.config));
+  const resetDue = isResetDue({ zone: view.zone, usagePercentage: view.percentage }, options.config.snapshot);
+  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config), resetDue })) return NEUTRAL2;
+  const action = zoneAction(view.zone, options.config.snapshot, { mode: restartMode(options.config), invoke: options.descriptor.skillInvocation, usagePercentage: view.percentage });
   return { kind: "context", block: renderTelemetryBlock({ turn, turnCeiling: redStartTurn(options.config.telemetry.zones), usagePercentage: view.percentage, usage: view.reading, zone: view.zone, action, debug: isDebugModeInEffect(options.config) }) };
 }
 async function handleResponseEnd(options, event) {
@@ -19166,7 +19216,7 @@ function renderPiToolResult(payload, block) {
 // src/infrastructure/harnesses/pi/runtime.ts
 var HARNESS = "pi";
 var ESTIMATION = { baselineTokens: 15e3, tokensPerTurn: 150 };
-var piDescriptor = { harness: HARNESS, capabilities: PI_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: "/new" };
+var piDescriptor = { harness: HARNESS, capabilities: PI_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: "/new", skillInvocation: PI_SKILL_INVOCATION };
 function rootOf(context) {
   return textValue(context.cwd);
 }