context-brake 1.0.0 → 1.1.0

package/dist/src/core/contracts/diagnostics.d.ts

@@ -440,8 +440,23 @@ export declare const doctorReportSchema: z.ZodObject<{
             YELLOW: "YELLOW";
             RED: "RED";
         }>;
+        triggerPercentage: z.ZodOptional<z.ZodNumber>;
         command: z.ZodNullable<z.ZodString>;
         resumeCommand: z.ZodNullable<z.ZodString>;
+        invocations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            harness: z.ZodEnum<{
+                cursor: "cursor";
+                "claude-code": "claude-code";
+                "codex-cli": "codex-cli";
+                "github-copilot-cli": "github-copilot-cli";
+                opencode: "opencode";
+                pi: "pi";
+                "oh-my-pi": "oh-my-pi";
+                "antigravity-cli": "antigravity-cli";
+            }>;
+            command: z.ZodString;
+            resumeCommand: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     contextWindow: z.ZodOptional<z.ZodObject<{
         bridge: z.ZodEnum<{
@@ -449,8 +464,14 @@ export declare const doctorReportSchema: z.ZodObject<{
             installed: "installed";
             absent: "absent";
         }>;
+        mod: z.ZodEnum<{
+            installed: "installed";
+            absent: "absent";
+            reporting: "reporting";
+        }>;
         source: z.ZodEnum<{
             contextWindowCeiling: "contextWindowCeiling";
+            mod: "mod";
             statusline: "statusline";
         }>;
         lastWindowTokens: z.ZodNullable<z.ZodNumber>;

package/dist/src/core/contracts/diagnostics.js

@@ -20,7 +20,8 @@ const harnessPlan = z.object({ harness: z.enum(HARNESS_IDS), outcome: z.enum(['p
 const outcome = z.object({ path: z.string(), status: z.enum(['planned', 'applied', 'unchanged', 'skipped', 'failed']), detail: z.string().nullable() }).strict();
 const plan = z.object({ schemaVersion: z.literal(1), projectRoot: z.string(), changes: z.array(fileChange), conflicts: z.array(conflict), harnesses: z.array(harnessPlan), requiresConfirmation: z.boolean() }).strict();
 export const installReportSchema = z.object({ schemaVersion: z.literal(1), command: z.enum(['init', 'remove']), mode: z.enum(['dry_run', 'applied']), status: z.enum(['success', 'warnings', 'errors']), exitCode: z.union([z.literal(0), z.literal(1), z.literal(2)]), detections: z.array(detection), plan, outcomes: z.array(outcome), findings: z.array(finding) }).strict();
-const snapshotReport = z.object({ triggerZone: z.enum(SNAPSHOT_TRIGGER_ZONES), command: z.string().nullable(), resumeCommand: z.string().nullable() }).strict();
+const invocationReport = z.object({ harness: z.enum(HARNESS_IDS), command: z.string(), resumeCommand: z.string().nullable() }).strict();
+const snapshotReport = z.object({ triggerZone: z.enum(SNAPSHOT_TRIGGER_ZONES), triggerPercentage: z.optional(z.number().int().min(1).max(100)), command: z.string().nullable(), resumeCommand: z.string().nullable(), invocations: z.optional(z.array(invocationReport)) }).strict();
 const sessionUsage = z.object({ percentage: z.number().int().nonnegative(), usedTokens: z.number().int().nonnegative(), windowTokens: z.number().int().positive(), zone: z.enum(ZONES), source: z.enum(USAGE_SOURCES), at: z.string() }).strict();
 const activeSession = z.object({ harness: z.enum(HARNESS_IDS), sessionId: z.string().nullable(), lastActivityAt: z.string(), usage: sessionUsage.nullable() }).strict();
 export const doctorReportSchema = z.object({ schemaVersion: z.literal(1), command: z.literal('doctor'), status: z.enum(['healthy', 'warnings', 'errors']), exitCode: z.union([z.literal(0), z.literal(1), z.literal(2)]), detections: z.array(detection), integrations: z.array(integration), findings: z.array(finding), snapshot: snapshotReport.optional(), contextWindow: contextWindowReportSchema.optional(), activeSessions: z.array(activeSession).optional(), debugMode: z.optional(z.literal(true)) }).strict();

package/dist/src/core/contracts/manifest.d.ts

@@ -13,11 +13,17 @@ export type ManagedEntry = {
     path: string;
     identity: string;
 };
+export type ConfigOrigin = {
+    path: string;
+    created: boolean;
+    addedKeys: readonly string[];
+};
 export type InstallationManifest = {
     schemaVersion: 1;
     packageVersion: string;
     assets: readonly ManagedAsset[];
     entries: readonly ManagedEntry[];
+    configOrigins?: readonly ConfigOrigin[] | undefined;
 };
 export interface ManifestStore {
     load(): Promise<InstallationManifest | null>;
@@ -44,6 +50,11 @@ export declare const managedEntrySchema: z.ZodObject<{
     path: z.ZodString;
     identity: z.ZodString;
 }, z.core.$strict>;
+export declare const configOriginSchema: z.ZodObject<{
+    path: z.ZodString;
+    created: z.ZodBoolean;
+    addedKeys: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
 export declare const installationManifestSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     packageVersion: z.ZodString;
@@ -66,4 +77,9 @@ export declare const installationManifestSchema: z.ZodObject<{
         path: z.ZodString;
         identity: z.ZodString;
     }, z.core.$strict>>;
+    configOrigins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        created: z.ZodBoolean;
+        addedKeys: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/src/core/contracts/manifest.js

@@ -12,9 +12,15 @@ export const managedEntrySchema = z.object({
     path: z.string(),
     identity: z.string().min(1),
 }).strict();
+export const configOriginSchema = z.object({
+    path: z.string(),
+    created: z.boolean(),
+    addedKeys: z.array(z.string().min(1)),
+}).strict();
 export const installationManifestSchema = z.object({
     schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
     packageVersion: z.string().min(1),
     assets: z.array(managedAssetSchema),
     entries: z.array(managedEntrySchema),
+    configOrigins: z.array(configOriginSchema).optional(),
 }).strict();

package/dist/src/core/contracts/runtime.d.ts

@@ -1,4 +1,5 @@
 import type { CapabilityDefinition, HarnessId } from './harness.js';
+import type { SkillInvocationFormat } from './skill-invocation.js';
 export type SessionKey = {
     readonly harness: HarnessId;
     readonly sessionId: string;
@@ -47,4 +48,5 @@ export type RuntimeDescriptor = {
     readonly capabilities: readonly CapabilityDefinition[];
     readonly estimation: EstimationConstants;
     readonly newSessionCommand: string | null;
+    readonly skillInvocation: SkillInvocationFormat;
 };

package/dist/src/core/contracts/skill-catalog.d.ts

@@ -0,0 +1,11 @@
+import type { HarnessId } from './harness.js';
+export type CatalogSkill = {
+    readonly name: string;
+    readonly description: string;
+    readonly folder: string;
+};
+export type SkillCatalog = {
+    readonly skills: readonly CatalogSkill[];
+    readonly warnings: readonly string[];
+};
+export type SkillCatalogReader = (harness: HarnessId, projectRoot: string) => Promise<SkillCatalog>;

package/dist/src/core/contracts/skill-catalog.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/contracts/skill-invocation.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessId } from './harness.js';
+export type SkillInvocationFormat = (skill: string) => string;
+export type SkillInvocationResolver = (harness: HarnessId) => SkillInvocationFormat;

package/dist/src/core/contracts/skill-invocation.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/contracts/skill-name.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod/mini';
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+export declare function isSkillName(value: string): boolean;
+export declare function skillNameProblem(value: string): string | null;
+export declare const skillNameSchema: z.ZodMiniString<string>;

package/dist/src/core/contracts/skill-name.js

@@ -0,0 +1,31 @@
+import { z } from 'zod/mini';
+export const MAX_SKILL_NAME_LENGTH = 64;
+const NAME_SEGMENT = '[a-z0-9]+(?:-[a-z0-9]+)*';
+const NAMESPACE_SEPARATOR = ':';
+const INVOCATION_CHARACTERS = ['/', '$', '@'];
+const MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+    return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+const PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+const SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits('$')}${NAME_SEGMENT}$`);
+const SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+export function isSkillName(value) {
+    return SKILL_NAME_PATTERN.test(value);
+}
+export 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}`;
+}
+export const skillNameSchema = z.string().check((ctx) => {
+    const message = skillNameProblem(ctx.value);
+    if (message !== null)
+        ctx.issues.push({ code: 'custom', input: ctx.value, message });
+});
+z.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });

package/dist/src/core/services/brake-engine.js

@@ -7,7 +7,7 @@ import { nextTurn, summarizeLedger } from './session-counters.js';
 import { readZone } from './session-zone.js';
 import { renderTelemetryBlock } from './telemetry-block.js';
 import { redStartTurn } from './zone-classifier.js';
-import { zoneAction } from './zone-guidance.js';
+import { isResetDue, zoneAction } from './zone-guidance.js';
 import { handleSessionReset } from './session-reset-handler.js';
 const NEUTRAL = { kind: 'neutral' };
 export function createBrakeEngine(options) { return { handle: (event, input) => handleEvent(options, event, input ?? {}) }; }
@@ -36,9 +36,10 @@ async function handlePreInvocation(options, event, input) {
     return telemetryDecision(options, summary.turns, readZone(options, { summary, turns: summary.turns, observedCharacters: 0, measured: input.measured }));
 }
 async function telemetryDecision(options, turn, view) {
-    if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(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 NEUTRAL;
-    const action = zoneAction(view.zone, options.config.snapshot, restartMode(options.config));
+    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) {

package/dist/src/core/services/doctor-report-extras.d.ts

@@ -1,11 +1,13 @@
 import type { ContextBrakeConfig } from '../contracts/configuration.js';
 import type { ContextWindowReport } from '../contracts/context-window-report.js';
 import type { DiagnosticFinding, DoctorReport } from '../contracts/diagnostics.js';
+import type { SkillInvocationResolver } from '../contracts/skill-invocation.js';
 import type { BuildDoctorReportInput } from './report-service.js';
 export type DoctorExtrasInput = {
     readonly config: ContextBrakeConfig | null;
     readonly planPresent: boolean;
     readonly contextWindow: ContextWindowReport | undefined;
     readonly sessions: DoctorReport['activeSessions'];
+    readonly invocations?: SkillInvocationResolver | undefined;
 };
 export declare function doctorReportExtras(input: DoctorExtrasInput, findings: readonly DiagnosticFinding[]): Omit<BuildDoctorReportInput, 'detections' | 'integrations'>;

package/dist/src/core/services/doctor-report-extras.js

@@ -1,18 +1,23 @@
 import { isDebugModeInEffect } from './debug-mode-merge.js';
 export function doctorReportExtras(input, findings) {
     return {
-        findings: [...findings, ...bridgeAbsentFindings(input.contextWindow)],
-        snapshot: snapshotReport(input.config), contextWindow: input.contextWindow, activeSessions: input.sessions,
+        findings: [...findings, ...modFindings(input.contextWindow), ...bridgeAbsentFindings(input.contextWindow)],
+        snapshot: snapshotReport(input.config, input.invocations), contextWindow: input.contextWindow, activeSessions: input.sessions,
         debugMode: isDebugModeInEffect(input.config),
     };
 }
-function snapshotReport(config) {
+function snapshotReport(config, resolve) {
     if (config === null)
         return undefined;
-    return { triggerZone: config.snapshot.triggerZone, command: config.snapshot.command ?? null, resumeCommand: config.snapshot.resumeCommand ?? null };
+    const { triggerZone, triggerPercentage, command, resumeCommand } = config.snapshot;
+    const trigger = triggerPercentage === undefined ? {} : { triggerPercentage };
+    const report = { triggerZone, ...trigger, command: command ?? null, resumeCommand: resumeCommand ?? null };
+    if (command === undefined || resolve === undefined)
+        return report;
+    return { ...report, invocations: config.activeHarnesses.map((harness) => ({ harness, command: resolve(harness)(command), resumeCommand: resumeCommand === undefined ? null : resolve(harness)(resumeCommand) })) };
 }
 function bridgeAbsentFindings(contextWindow) {
-    if (contextWindow?.bridge !== 'absent')
+    if (contextWindow?.bridge !== 'absent' || contextWindow.mod !== 'absent')
         return [];
     return [{
             code: 'STATUSLINE_BRIDGE_ABSENT', severity: 'warning', scope: 'harness', harness: 'claude-code', path: null,
@@ -21,3 +26,15 @@ function bridgeAbsentFindings(contextWindow) {
             remediation: 'Run context-brake init. After --no-statusline-bridge, run context-brake init --statusline-bridge.',
         }];
 }
+function modFindings(contextWindow) {
+    if (contextWindow?.mod === 'reporting')
+        return [{ code: 'CONTEXT_MOD_READY', severity: 'ok', scope: 'harness', harness: 'claude-code', path: null, message: 'The Claude Code mod reports the context window.', impact: null, remediation: null }];
+    if (contextWindow?.mod !== 'installed' || contextWindow.bridge === 'installed')
+        return [];
+    return [{
+            code: 'CONTEXT_MOD_SILENT', severity: 'warning', scope: 'harness', harness: 'claude-code', path: null,
+            message: 'The ContextBrake mod is installed, but no Claude Code session has reported the context yet.',
+            impact: 'The context window falls back to contextWindowCeiling and usage to the transcript or an estimate.',
+            remediation: 'Start Claude Code in this project and trust the folder. Mods stay off under disableAllHooks, --safe-mode, --bare, an organization managed policy, and in Desktop WSL sessions. Claude Code also keeps one marketplace named context-brake-local per user, so the mod of another repository can be the one that loads; run context-brake init in that repository too, or use the status line bridge with context-brake init --statusline-bridge.',
+        }];
+}

package/dist/src/core/services/doctor-service.d.ts

@@ -5,6 +5,7 @@ import type { FileSnapshot } from '../contracts/changes.js';
 import { type DetectionSources, type HarnessId } from '../contracts/harness.js';
 import type { InstallationManifest } from '../contracts/manifest.js';
 import { type RuntimeStateReading } from './runtime-error-checks.js';
+import type { SkillInvocationResolver } from '../contracts/skill-invocation.js';
 export type DoctorInput = {
     projectRoot: string;
     config: ContextBrakeConfig | null;
@@ -20,5 +21,6 @@ export type DoctorInput = {
     runtimeState?: RuntimeStateReading | null;
     contextWindow?: DoctorReport['contextWindow'];
     now?: Date | undefined;
+    invocations?: SkillInvocationResolver;
 };
 export declare function diagnoseProject(input: DoctorInput): Promise<DoctorReport>;

package/dist/src/core/services/doctor-service.js

@@ -78,5 +78,5 @@ export async function diagnoseProject(input) {
     if (input.runtimeState)
         allFindings.push(...runtimeErrorFindings(input.runtimeState));
     const sessions = input.now === undefined ? [] : activeSessions(input.runtimeState?.ledgers ?? [], { now: input.now, zones: effective.telemetry.zones });
-    return buildDoctorReport({ detections, integrations, ...doctorReportExtras({ config: input.config, planPresent: false, contextWindow: targetIds.has('claude-code') ? input.contextWindow : undefined, sessions }, allFindings) });
+    return buildDoctorReport({ detections, integrations, ...doctorReportExtras({ config: input.config, planPresent: false, contextWindow: targetIds.has('claude-code') ? input.contextWindow : undefined, sessions, invocations: input.invocations }, allFindings) });
 }

package/dist/src/core/services/failure-policy.js

@@ -47,7 +47,7 @@ export async function resolveFailure(input) {
     return { kind: 'neutral' };
 }
 function deadlineBootDecision(input) {
-    const text = resumeText((input.config ?? DEFAULT_CONFIG).snapshot);
+    const text = resumeText((input.config ?? DEFAULT_CONFIG).snapshot, input.descriptor?.skillInvocation);
     return text === null ? { kind: 'neutral' } : { kind: 'context', block: text };
 }
 export async function recordRuntimeFailure(errors, record) {

package/dist/src/core/services/injection-policy.d.ts

@@ -5,5 +5,6 @@ export type InjectionInput = {
     readonly zone: Zone;
     readonly usagePercentage: number;
     readonly debug: boolean;
+    readonly resetDue?: boolean | undefined;
 };
 export declare function decideInjection(input: InjectionInput): boolean;

package/dist/src/core/services/injection-policy.js

@@ -1,5 +1,5 @@
 export function decideInjection(input) {
-    if (input.debug || input.telemetry.injectionMode === 'always')
+    if (input.debug || input.resetDue === true || input.telemetry.injectionMode === 'always')
         return true;
     return input.zone !== 'GREEN' || input.usagePercentage >= input.telemetry.activationThresholdPercentage;
 }

package/dist/src/core/services/installation-adapters.d.ts

@@ -1,12 +1,13 @@
 import type { HarnessAdapter, HarnessContext } from '../contracts/adapter.js';
 import type { HarnessInstallPlan, PlannedChange, PlanConflict } from '../contracts/changes.js';
 import type { HarnessDetection } from '../contracts/harness.js';
-import type { ManagedAsset, ManagedEntry } from '../contracts/manifest.js';
+import type { ConfigOrigin, ManagedAsset, ManagedEntry } from '../contracts/manifest.js';
 export declare function planAdapters(adapters: readonly HarnessAdapter[], active: readonly HarnessDetection[], ctx: HarnessContext): Promise<{
     changes: PlannedChange[];
     conflicts: PlanConflict[];
     entries: ManagedEntry[];
     assets: ManagedAsset[];
+    configOrigins: ConfigOrigin[];
     harnesses: HarnessInstallPlan[];
     findings: {
         code: string;

package/dist/src/core/services/installation-adapters.js

@@ -4,6 +4,7 @@ export async function planAdapters(adapters, active, ctx) {
     const conflicts = [];
     const entries = [];
     const assets = [];
+    const configOrigins = [];
     const harnesses = [];
     const findings = [];
     for (const d of active) {
@@ -15,6 +16,7 @@ export async function planAdapters(adapters, active, ctx) {
         conflicts.push(...aPlan.conflicts);
         findings.push(...(aPlan.findings ?? []));
         entries.push(...aPlan.entries);
+        configOrigins.push(...(aPlan.configOrigins ?? []));
         for (const c of aPlan.changes)
             if (c.owner === 'runtime_asset' && c.content)
                 assets.push({ path: c.path, kind: 'runtime_asset', sha256: hashString(c.content) });
@@ -24,5 +26,5 @@ export async function planAdapters(adapters, active, ctx) {
         const profile = adapter.capabilityProfile();
         harnesses.push({ harness: d.harness, outcome, supportLevel: profile.supportLevel, limitations: [...profile.limitations] });
     }
-    return { changes, conflicts, entries, assets, harnesses, findings };
+    return { changes, conflicts, entries, assets, configOrigins, harnesses, findings };
 }

package/dist/src/core/services/installation-builder.js

@@ -6,6 +6,7 @@ import { applyDebugMode } from './debug-mode-merge.js';
 import { applyGitIgnore } from './gitignore-merge.js';
 import { normalizeTurnLimits } from './config-legacy-checks.js';
 import { applyExclusion } from './harness-exclusion.js';
+import { describeTrigger } from './trigger-text.js';
 const KEEP = { kind: 'keep' };
 const CONFIG_KEY_ORDER = Object.keys(configurationSchema.shape);
 const DEBUG_SUMMARY = { set: 'set the debug mode (agent prints context usage)', remove: 'remove the debug mode' };
@@ -60,7 +61,7 @@ function configSummary(updates) {
 }
 function snapshotSummary(section) {
     if (section.command === undefined)
-        return `no snapshot command, so only zone headers will be injected (trigger: ${section.triggerZone})`;
+        return `no snapshot command, so only zone headers will be injected (trigger: ${describeTrigger(section)})`;
     const resume = section.resumeCommand === undefined ? '' : `, resume command ${section.resumeCommand}`;
-    return `snapshot command ${section.command} at ${section.triggerZone}${resume}`;
+    return `snapshot command ${section.command} at ${describeTrigger(section)}${resume}`;
 }

package/dist/src/core/services/installation-service.js

@@ -39,7 +39,7 @@ export async function planInstallation(input) {
     const preservedAssets = (input.previousManifest?.assets ?? []).filter((a) => modifiedPaths.has(a.path));
     const adapterAssets = [...ap.assets.filter((a) => !modifiedPaths.has(a.path)), ...preservedAssets, ...extras.assets];
     const allAssets = buildManagedAssets(cfg.change.content ?? '', adapterAssets);
-    const manifestChanges = active.length === 0 && !input.previousManifest ? [] : [planManifestChange({ root: input.projectRoot, assets: allAssets, entries: ap.entries, prev: input.previousManifest ?? null, pkgVer: input.packageVersion, snapshot: input.allSnapshots.find((s) => s.path === MANIFEST_RELATIVE_PATH) })];
+    const manifestChanges = active.length === 0 && !input.previousManifest ? [] : [planManifestChange({ root: input.projectRoot, assets: allAssets, entries: ap.entries, configOrigins: ap.configOrigins, prev: input.previousManifest ?? null, pkgVer: input.packageVersion, snapshot: input.allSnapshots.find((s) => s.path === MANIFEST_RELATIVE_PATH) })];
     const plannedChanges = [cfg.change, ...manifestChanges, ...protection.changes, ...extras.changes, ...removals.changes];
     const ignore = planGitIgnoreForInstall({ root: input.projectRoot, enabled: cfg.config.gitIgnore !== false, insideGit: input.insideGit ?? false, hasInstall: manifestChanges.length > 0, assetPaths: allAssets.map((asset) => asset.path), changes: plannedChanges, snapshots: input.allSnapshots });
     const conflicts = [...ap.conflicts, ...protection.conflicts, ...ignore.conflicts];

package/dist/src/core/services/manifest-change.d.ts

@@ -1,9 +1,10 @@
 import type { FileSnapshot, PlannedChange } from '../contracts/changes.js';
-import { type InstallationManifest, type ManagedAsset, type ManagedEntry } from '../contracts/manifest.js';
+import { type ConfigOrigin, type InstallationManifest, type ManagedAsset, type ManagedEntry } from '../contracts/manifest.js';
 export type ManifestChangeInput = {
     root: string;
     assets: readonly ManagedAsset[];
     entries: readonly ManagedEntry[];
+    configOrigins?: readonly ConfigOrigin[] | undefined;
     prev: InstallationManifest | null;
     pkgVer: string;
     snapshot?: FileSnapshot | null | undefined;

package/dist/src/core/services/manifest-change.js

@@ -1,7 +1,8 @@
 import { resolve } from 'node:path';
 import { MANIFEST_RELATIVE_PATH } from '../contracts/manifest.js';
 export function planManifestChange(input) {
-    const manifest = { schemaVersion: 1, packageVersion: input.pkgVer, assets: input.assets, entries: input.entries };
+    const origins = input.configOrigins ?? [];
+    const manifest = { schemaVersion: 1, packageVersion: input.pkgVer, assets: input.assets, entries: input.entries, ...(origins.length > 0 ? { configOrigins: origins } : {}) };
     const content = `${JSON.stringify(manifest, null, 2)}\n`;
     const defaultPath = resolve(input.root, MANIFEST_RELATIVE_PATH).replace(/\\/g, '/');
     const realPath = (input.snapshot?.realPath ?? defaultPath).replace(/\\/g, '/');

package/dist/src/core/services/session-reset-handler.js

@@ -13,7 +13,7 @@ export async function handleSessionReset(options, event, hooks = {}) {
     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) {

package/dist/src/core/services/skill-candidates.d.ts

@@ -0,0 +1,16 @@
+import type { HarnessId } from '../contracts/harness.js';
+import type { CatalogSkill } from '../contracts/skill-catalog.js';
+export type SkillOrigin = {
+    readonly harness: HarnessId;
+    readonly folder: string;
+};
+export type SkillCandidate = {
+    readonly name: string;
+    readonly description: string;
+    readonly origins: readonly SkillOrigin[];
+};
+export type HarnessCatalog = {
+    readonly harness: HarnessId;
+    readonly skills: readonly CatalogSkill[];
+};
+export declare function mergeCatalogs(catalogs: readonly HarnessCatalog[]): SkillCandidate[];

package/dist/src/core/services/skill-candidates.js

@@ -0,0 +1,14 @@
+function byHarness(left, right) {
+    return left.harness.localeCompare(right.harness) || left.folder.localeCompare(right.folder);
+}
+export function mergeCatalogs(catalogs) {
+    const byName = new Map();
+    for (const { harness, skills } of catalogs) {
+        for (const skill of skills) {
+            const known = byName.get(skill.name) ?? { description: skill.description, origins: [] };
+            known.origins.push({ harness, folder: skill.folder });
+            byName.set(skill.name, known);
+        }
+    }
+    return [...byName].map(([name, { description, origins }]) => ({ name, description, origins: [...origins].sort(byHarness) }));
+}

package/dist/src/core/services/skill-invocation.d.ts

@@ -0,0 +1,4 @@
+export declare function slashInvocation(skill: string): string;
+export declare function dollarInvocation(skill: string): string;
+export declare function skillSlashInvocation(skill: string): string;
+export declare function sentenceInvocation(skill: string): string;

package/dist/src/core/services/skill-invocation.js

@@ -0,0 +1,12 @@
+export function slashInvocation(skill) {
+    return `/${skill}`;
+}
+export function dollarInvocation(skill) {
+    return `$${skill}`;
+}
+export function skillSlashInvocation(skill) {
+    return `/skill:${skill}`;
+}
+export function sentenceInvocation(skill) {
+    return `use the ${skill} skill`;
+}

package/dist/src/core/services/skill-ranking.d.ts

@@ -0,0 +1,7 @@
+import type { SkillCandidate } from './skill-candidates.js';
+export type SkillRole = 'snapshot' | 'resume';
+export type RankOptions = {
+    readonly exclude?: string | undefined;
+};
+export declare function scoreSkill(role: SkillRole, candidate: SkillCandidate): number;
+export declare function rankSkills(role: SkillRole, candidates: readonly SkillCandidate[], options?: RankOptions): SkillCandidate[];

package/dist/src/core/services/skill-ranking.js

@@ -0,0 +1,25 @@
+const ROLE_TERMS = {
+    snapshot: ['snapshot', 'handoff', 'checkpoint'],
+    resume: ['resume', 'continue', 'retomar', 'retomada', 'continuar', 'orchestrate', 'flow'],
+};
+const NAME_SCORE = 100;
+const DESCRIPTION_SCORE = 10;
+const DESCRIPTION_WINDOW = 300;
+function mentions(text, terms) {
+    const lowered = text.toLowerCase();
+    return terms.some((term) => lowered.includes(term));
+}
+export function scoreSkill(role, candidate) {
+    const terms = ROLE_TERMS[role];
+    if (mentions(candidate.name, terms))
+        return NAME_SCORE;
+    return mentions(candidate.description.slice(0, DESCRIPTION_WINDOW), terms) ? DESCRIPTION_SCORE : 0;
+}
+export function rankSkills(role, candidates, options = {}) {
+    return candidates
+        .filter((candidate) => candidate.name !== options.exclude)
+        .map((candidate) => ({ candidate, score: scoreSkill(role, candidate) }))
+        .filter(({ score }) => score > 0)
+        .sort((left, right) => right.score - left.score || right.candidate.origins.length - left.candidate.origins.length || left.candidate.name.localeCompare(right.candidate.name))
+        .map(({ candidate }) => candidate);
+}

package/dist/src/core/services/snapshot-merge.d.ts

@@ -2,6 +2,7 @@ import { type SnapshotConfig } from '../contracts/configuration.js';
 export type SnapshotFlags = {
     readonly command?: string | undefined;
     readonly triggerZone?: string | undefined;
+    readonly triggerPercentage?: number | undefined;
     readonly resumeCommand?: string | undefined;
     readonly clearCommand: boolean;
 };

package/dist/src/core/services/snapshot-merge.js

@@ -1,24 +1,31 @@
 import { snapshotSchema } from '../contracts/configuration.js';
 const SECTION_PATH = 'snapshot';
+const CONFIG_FILE = 'context-brake.config.json';
+const FLAG_BY_FIELD = { command: '--snapshot-command <skill>', resumeCommand: '--resume-command <skill>', triggerZone: '--snapshot-trigger <YELLOW|RED>', triggerPercentage: '--snapshot-trigger-percentage <1-100>' };
 const CLEAR_CONFLICT = '--no-snapshot-command cannot be combined with --snapshot-command or --resume-command.';
 export function mergeSnapshot(current, flags) {
     if (flags.clearCommand && (flags.command !== undefined || flags.resumeCommand !== undefined))
         return { error: CLEAR_CONFLICT };
-    if (!flags.clearCommand && [flags.command, flags.triggerZone, flags.resumeCommand].every((value) => value === undefined))
+    if (!flags.clearCommand && [flags.command, flags.triggerZone, flags.triggerPercentage, flags.resumeCommand].every((value) => value === undefined))
         return { update: { kind: 'keep' } };
-    const base = flags.clearCommand ? { triggerZone: current?.triggerZone } : { ...current };
-    const result = snapshotSchema.safeParse(withoutUndefined({ ...base, ...definedFields(flags) }));
+    const result = snapshotSchema.safeParse(withoutUndefined({ ...baseSection(current, flags), ...definedFields(flags) }));
     if (result.success)
         return { update: { kind: 'set', section: result.data } };
     const issue = result.error.issues[0];
     const path = [SECTION_PATH, ...(issue?.path ?? [])].join('.');
-    return { error: `Invalid snapshot option: ${path} ${issue?.message ?? 'is invalid'}.` };
+    const flag = FLAG_BY_FIELD[String(issue?.path[0])];
+    const where = flag === undefined ? '' : ` Set it with ${flag} or in ${CONFIG_FILE}.`;
+    return { error: `Invalid snapshot option: ${path} ${issue?.message ?? 'is invalid'}.${where}` };
 }
 export function applySnapshot(config, update) {
     return update.kind === 'keep' ? config : { ...config, snapshot: update.section };
 }
+function baseSection(current, flags) {
+    const trigger = { triggerZone: current?.triggerZone, triggerPercentage: flags.triggerZone === undefined ? current?.triggerPercentage : undefined };
+    return flags.clearCommand ? trigger : { ...current, ...trigger };
+}
 function definedFields(flags) {
-    return withoutUndefined({ command: flags.command, triggerZone: flags.triggerZone, resumeCommand: flags.resumeCommand });
+    return withoutUndefined({ command: flags.command, triggerZone: flags.triggerZone, triggerPercentage: flags.triggerPercentage, resumeCommand: flags.resumeCommand });
 }
 function withoutUndefined(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));

package/dist/src/core/services/trigger-text.d.ts

@@ -0,0 +1,5 @@
+export type TriggerSetting = {
+    readonly triggerZone: string;
+    readonly triggerPercentage?: number | null | undefined;
+};
+export declare function describeTrigger(setting: TriggerSetting): string;

package/dist/src/core/services/trigger-text.js

@@ -0,0 +1,4 @@
+export function describeTrigger(setting) {
+    const percentage = setting.triggerPercentage ?? null;
+    return percentage === null ? setting.triggerZone : `${percentage}% of the context window`;
+}

package/dist/src/core/services/zone-guidance.d.ts

@@ -1,6 +1,17 @@
 import type { SnapshotConfig } from '../contracts/configuration.js';
+import type { SkillInvocationFormat } from '../contracts/skill-invocation.js';
 import { type Zone } from '../contracts/zones.js';
 import type { RestartMode } from './restart-mode.js';
-export declare function zoneAction(zone: Zone, snapshot: SnapshotConfig, mode?: RestartMode): string;
+export type GuidanceOptions = {
+    readonly mode?: RestartMode | undefined;
+    readonly invoke?: SkillInvocationFormat | undefined;
+    readonly usagePercentage?: number | undefined;
+};
+export type ZoneUsage = {
+    readonly zone: Zone;
+    readonly usagePercentage: number;
+};
+export declare function isResetDue(reading: ZoneUsage, snapshot: SnapshotConfig): boolean;
+export declare function zoneAction(zone: Zone, snapshot: SnapshotConfig, options?: GuidanceOptions): string;
 export declare function handoffResumeText(archivedPath: string): string;
-export declare function resumeText(snapshot: SnapshotConfig): string | null;
+export declare function resumeText(snapshot: SnapshotConfig, invoke?: SkillInvocationFormat): string | null;