@jeger-ai/opengantry 3.7.0 → 3.8.0

package/dist/cli/lib/cage/cage-report.d.ts

@@ -1,10 +1,14 @@
-import type { CageRuleId } from "./cage-rules.js";
+import { type CageRuleId, type CageRuleSource } from "./cage-rules.js";
 import type { CageOutcome, CageResolvedChange } from "./cage-revert.js";
 export declare const CAGE_REPORT_SCHEMA: "gantry.cage-report.v1";
-/** Detect-after-the-fact limits, stated in every cage report. */
+/** Limits with `--no-watch` (after-exit check only), stated in every such report. */
 export declare const CAGE_LIMITS: readonly string[];
 /** One-line stderr form of {@link CAGE_LIMITS}; `--json` keeps the full list. */
 export declare const CAGE_LIMITS_SUMMARY = "after-exit check only; reads, network calls and writes outside the protected set are not detected";
+/** Limits in watch mode (the default): live restore, not prevention. */
+export declare const CAGE_WATCH_LIMITS: readonly string[];
+/** One-line stderr form of {@link CAGE_WATCH_LIMITS}. */
+export declare const CAGE_WATCH_LIMITS_SUMMARY = "live restore, not blocking; reads, network calls and writes outside the protected set are not detected";
 /** Printed once under a violation report: the path from cage to project-specific missions. */
 export declare const CAGE_UPGRADE_FOOTER = "Need project-specific boundaries or task contracts? Run: npx -p @jeger-ai/opengantry gantry init";
 export type CageStatus = "ok" | "violations_reverted" | "violations_unresolved" | "runtime_error";
@@ -13,6 +17,9 @@ export interface CageReportChange {
     path: string;
     kind: "added" | "modified" | "deleted";
     rule: CageRuleId;
+    source: CageRuleSource;
+    /** A revert rule downgraded to report by `--allow-override`. */
+    overridden: boolean;
     sha256_before: string | null;
     sha256_after: string | null;
     outcome: CageOutcome;
@@ -32,7 +39,29 @@ export interface CageReport {
     max_file_bytes: number;
     protected_files: number;
     manifest_zones: number;
+    /**
+     * `.cage.yaml` at the cage root: whether it exists, how many protect entries it adds, and whether it is
+     * committed unchanged (null without a config or outside git).
+     */
+    cage_config: {
+        present: boolean;
+        entries: number;
+        committed: boolean | null;
+    };
+    /** Paths downgraded from revert to report for this run by `--allow-override`. */
+    overrides: string[];
     changes: CageReportChange[];
+    watch: {
+        enabled: boolean;
+        interval_ms: number | null;
+        live_restores: number;
+        contested: string[];
+        session_log: string | null;
+    };
+    push_guard: {
+        enabled: boolean;
+        refused_pushes: number;
+    };
     limits: readonly string[];
 }
 export interface CageReportInput {
@@ -45,10 +74,16 @@ export interface CageReportInput {
     maxFileBytes: number;
     protectedFiles: number;
     manifestZones: number;
+    cageConfig: CageReport["cage_config"];
+    overrides: readonly string[];
     changes: readonly CageResolvedChange[];
+    watch: CageReport["watch"];
+    pushGuard: CageReport["push_guard"];
     signalExitCode: (signal: NodeJS.Signals) => number;
 }
 export declare function buildCageReport(input: CageReportInput): CageReport;
+/** Stderr banner for `--allow-override`, printed at start and again in the exit summary. */
+export declare function formatCageOverrideBanner(overrides: readonly string[]): string | null;
 /** Human summary (stderr), so it never mixes into the wrapped command's stdout. */
 export declare function formatCageReport(report: CageReport): string[];
 //# sourceMappingURL=cage-report.d.ts.map

package/dist/cli/lib/cage/cage-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cage-report.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAExE,eAAO,MAAM,kBAAkB,EAAG,uBAAgC,CAAC;AAEnE,iEAAiE;AACjE,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAMxC,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,sGACqE,CAAC;AAEtG,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,qGACoE,CAAC;AAErG,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,qBAAqB,GAAG,uBAAuB,GAAG,eAAe,CAAC;AAElG,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACvC,IAAI,EAAE,UAAU,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC;CACpD;AAqBD,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,CA0BlE;AAOD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAoB7D"}
+{"version":3,"file":"cage-report.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-report.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/cage/cage-report.js

@@ -1,5 +1,6 @@
+import { cageRuleSource } from "./cage-rules.js";
 export const CAGE_REPORT_SCHEMA = "gantry.cage-report.v1";
-/** Detect-after-the-fact limits, stated in every cage report. */
+/** Limits with `--no-watch` (after-exit check only), stated in every such report. */
 export const CAGE_LIMITS = [
     "detects protected-path writes after the command exits; it does not block them while it runs",
     "reads are not detected: the command can still read .env and other secrets",
@@ -9,6 +10,16 @@ export const CAGE_LIMITS = [
 ];
 /** One-line stderr form of {@link CAGE_LIMITS}; `--json` keeps the full list. */
 export const CAGE_LIMITS_SUMMARY = "after-exit check only; reads, network calls and writes outside the protected set are not detected";
+/** Limits in watch mode (the default): live restore, not prevention. */
+export const CAGE_WATCH_LIMITS = [
+    "restores protected-path writes about once per watch interval while the command runs; it does not block them",
+    "a change can be committed or used before the next check; the push guard covers git push from inside the session only",
+    "reads are not detected: the command can still read .env and other secrets",
+    "network and API side effects are not detected",
+    "writes outside the protected set, and outside the repository, are not checked",
+];
+/** One-line stderr form of {@link CAGE_WATCH_LIMITS}. */
+export const CAGE_WATCH_LIMITS_SUMMARY = "live restore, not blocking; reads, network calls and writes outside the protected set are not detected";
 /** Printed once under a violation report: the path from cage to project-specific missions. */
 export const CAGE_UPGRADE_FOOTER = "Need project-specific boundaries or task contracts? Run: npx -p @jeger-ai/opengantry gantry init";
 const VIOLATION_EXIT_CODE = 3;
@@ -45,21 +56,51 @@ export function buildCageReport(input) {
         max_file_bytes: input.maxFileBytes,
         protected_files: input.protectedFiles,
         manifest_zones: input.manifestZones,
+        cage_config: input.cageConfig,
+        overrides: [...input.overrides],
         changes: input.changes.map((c) => ({
             path: c.rel,
             kind: c.kind,
             rule: c.rule,
+            source: cageRuleSource(c.rule),
+            overridden: c.overridden,
             sha256_before: c.before?.sha256 ?? null,
             sha256_after: c.after?.sha256 ?? null,
             outcome: c.outcome,
             error_code: c.errorCode,
         })),
-        limits: CAGE_LIMITS,
+        watch: input.watch,
+        push_guard: input.pushGuard,
+        limits: input.watch.enabled ? CAGE_WATCH_LIMITS : CAGE_LIMITS,
     };
 }
 function changeLine(c) {
     const err = c.error_code ? ` ${c.error_code}` : "";
-    return `  ${c.outcome.padEnd(13)} ${c.kind.padEnd(8)} ${c.path} (${c.rule})${err}`;
+    const over = c.overridden ? ", overridden" : "";
+    return `  ${c.outcome.padEnd(13)} ${c.kind.padEnd(8)} ${c.path} (${c.rule}${over})${err}`;
+}
+/** Stderr banner for `--allow-override`, printed at start and again in the exit summary. */
+export function formatCageOverrideBanner(overrides) {
+    if (overrides.length === 0)
+        return null;
+    return `cage: OVERRIDE (--allow-override): changes are reported, not restored, under: ${overrides.join(", ")}`;
+}
+function sessionLines(report) {
+    const out = [];
+    const w = report.watch;
+    if (w.live_restores > 0) {
+        out.push(`cage: restored ${String(w.live_restores)} protected change(s) during the session`);
+    }
+    if (w.contested.length > 0) {
+        out.push(`cage: contested (kept being rewritten; restored once at exit): ${w.contested.join(", ")}`);
+    }
+    if (report.push_guard.refused_pushes > 0) {
+        out.push(`cage: refused ${String(report.push_guard.refused_pushes)} push(es) touching protected paths`);
+    }
+    if (w.session_log && (w.live_restores > 0 || report.push_guard.refused_pushes > 0)) {
+        out.push(`cage: session log: ${w.session_log}`);
+    }
+    return out;
 }
 /** Human summary (stderr), so it never mixes into the wrapped command's stdout. */
 export function formatCageReport(report) {
@@ -78,7 +119,12 @@ export function formatCageReport(report) {
     if (report.changes.some((c) => c.outcome === "detect_only")) {
         lines.push(`cage: detect_only files exceeded the ${String(report.max_file_bytes)}-byte per-file cap or the total snapshot budget and were not restored`);
     }
-    lines.push(`cage: exit ${String(report.exit_code)}; limits: ${CAGE_LIMITS_SUMMARY}`);
+    lines.push(...sessionLines(report));
+    const banner = formatCageOverrideBanner(report.overrides);
+    if (banner)
+        lines.push(banner);
+    const summary = report.watch.enabled ? CAGE_WATCH_LIMITS_SUMMARY : CAGE_LIMITS_SUMMARY;
+    lines.push(`cage: exit ${String(report.exit_code)}; limits: ${summary}`);
     if (report.status === "violations_reverted" || report.status === "violations_unresolved") {
         lines.push(`cage: ${CAGE_UPGRADE_FOOTER}`);
     }

package/dist/cli/lib/cage/cage-report.js.map

@@ -1 +1 @@
-{"version":3,"file":"cage-report.js","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-report.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cage-report.js","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-report.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/cage/cage-revert.d.ts

@@ -2,7 +2,7 @@ import type { CageChange } from "./cage-snapshot.js";
 /**
  * - `reverted`: baseline bytes (or symlink) restored
  * - `removed`: an added file was deleted
- * - `kept`: report-only rule (lockfiles); change left in place
+ * - `kept`: report-only rule (lockfiles, report entries, `--allow-override`); change left in place
  * - `reported`: `--report-only` run; change left in place
  * - `detect_only`: no baseline bytes (over size cap or budget); change left in place
  * - `revert_failed`: restore attempted and failed (`error_code` says why)

package/dist/cli/lib/cage/cage-rules.d.ts

@@ -1,24 +1,70 @@
 /**
  * Zero-config protected set for `gantry cage`. Paths are matched without any
- * manifest; manifest `forbidden_zones` are unioned in when the repo has one.
+ * manifest; manifest `forbidden_zones` and `.cage.yaml` `protect:` entries are
+ * unioned in when present. Nothing in the repo can remove a built-in rule.
  */
-export type CageRuleId = "ci_config" | "secrets" | "git_control" | "lockfile" | "manifest_forbidden_zone";
+export type CageRuleId = "ci_config" | "secrets" | "git_control" | "lockfile" | "cage_config" | "manifest_forbidden_zone" | "cage_protect";
+/** Where a rule comes from: shipped with cage, the GXT manifest, or the project's `.cage.yaml`. */
+export type CageRuleSource = "builtin" | "manifest" | "cage_yaml";
 /** `revert`: restore baseline bytes and fail. `report`: list the change but keep it. */
 export type CageRuleMode = "revert" | "report";
 export declare const CAGE_RULE_MODES: Readonly<Record<CageRuleId, CageRuleMode>>;
+export declare function cageRuleSource(rule: CageRuleId): CageRuleSource;
 /** Directory names skipped by the whole-tree basename scan (dependency and VCS bulk). */
 export declare const CAGE_SCAN_SKIP_DIRS: ReadonlySet<string>;
 /** A file or directory tree protected by absolute path. */
 export interface CageTarget {
     abs: string;
     rule: CageRuleId;
+    mode: CageRuleMode;
+    source: CageRuleSource;
+}
+/** A `.cage.yaml` glob, matched against root-relative POSIX paths found by the whole-tree scan. */
+export interface CageGlobTarget {
+    pattern: string;
+    re: RegExp;
+    mode: CageRuleMode;
+    source: "cage_yaml";
 }
 export interface CagePlan {
     root: string;
     targets: CageTarget[];
+    globs: CageGlobTarget[];
+    /** Root-relative paths whose revert rules `--allow-override` downgraded to report. */
+    overrides: string[];
     manifestZoneCount: number;
+    /** `committed` is null when there is no config or no git work tree. */
+    config: {
+        present: boolean;
+        entries: number;
+        committed: boolean | null;
+    };
+}
+/** How one path is protected after overrides; null when no rule matches. */
+export interface CagePathRule {
+    rule: CageRuleId;
+    mode: CageRuleMode;
+    overridden: boolean;
 }
 /** Rule for a file found by the whole-tree scan, keyed on its basename. */
 export declare function cageBasenameRule(name: string): CageRuleId | null;
-export declare function buildCagePlan(root: string): CagePlan;
+/**
+ * The strictest rule for a root-relative path (revert beats report), then `--allow-override`.
+ * Shared by the snapshot, override validation and the push guard so all three agree.
+ */
+export declare function classifyCagePath(plan: CagePlan, rel: string, opts?: {
+    overrides?: boolean;
+}): CagePathRule | null;
+/** Downgrade a revert rule to report when the path is overridden; harness rules never are. */
+export declare function applyCageOverride(plan: Pick<CagePlan, "overrides">, rel: string, hit: CagePathRule | null, enabled?: boolean): CagePathRule | null;
+/**
+ * Resolve the session's protected set. An invalid manifest, `.cage.yaml` or override throws, so cage
+ * fails closed before the wrapped command runs.
+ */
+export declare function buildCagePlan(root: string, opts?: {
+    overrides?: readonly string[];
+}): CagePlan;
+/** JSON form for the session push guard, so it checks the exact plan the session started with. */
+export declare function serializeCagePlan(plan: CagePlan): string;
+export declare function parseSerializedCagePlan(json: string): CagePlan;
 //# sourceMappingURL=cage-rules.d.ts.map

package/dist/cli/lib/cage/cage-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cage-rules.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-rules.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,yBAAyB,CAAC;AAE1G,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/C,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAOtE,CAAC;AAqBF,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAMlD,CAAC;AAEH,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIhE;AAwCD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAQpD"}
+{"version":3,"file":"cage-rules.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-rules.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,SAAS,GACT,aAAa,GACb,UAAU,GACV,aAAa,GACb,yBAAyB,GACzB,cAAc,CAAC;AAEnB,mGAAmG;AACnG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAElE,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/C,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAUtE,CAAC;AAKF,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAI/D;AAqBD,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAMlD,CAAC;AAEH,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,sFAAsF;IACtF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;CAC1E;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIhE;AA0DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,YAAY,GAAG,IAAI,CAYrH;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,GAAG,IAAI,EACxB,OAAO,UAAO,GACb,YAAY,GAAG,IAAI,CAGrB;AAmED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAAG,QAAQ,CAmBlG;AAWD,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGxD;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAG9D"}

package/dist/cli/lib/cage/cage-rules.js

@@ -1,16 +1,31 @@
 import fs from "node:fs";
 import path from "node:path";
+import { toPosixRel } from "../cli-io.js";
 import { REL_MANIFEST } from "../constants.js";
 import { gitRun } from "../git/git.js";
+import { GantryUserError } from "../errors.js";
 import { loadManifest } from "../manifest.js";
+import { CAGE_CONFIG_FILE, cageConfigCommitted, cageGlobToRegExp, loadCageConfig, normalizeCageRelPath, } from "./cage-config.js";
 export const CAGE_RULE_MODES = {
     ci_config: "revert",
     secrets: "revert",
     git_control: "revert",
     // Package managers legitimately rewrite lockfiles; surface the change, never undo it.
     lockfile: "report",
+    cage_config: "revert",
     manifest_forbidden_zone: "revert",
+    // Default only: each `.cage.yaml` entry carries its own mode.
+    cage_protect: "revert",
 };
+/** Rules `--allow-override` can never downgrade: they protect the harness itself. */
+const NON_OVERRIDABLE_RULES = new Set(["git_control", "cage_config"]);
+export function cageRuleSource(rule) {
+    if (rule === "manifest_forbidden_zone")
+        return "manifest";
+    if (rule === "cage_protect")
+        return "cage_yaml";
+    return "builtin";
+}
 /** Root-anchored CI paths (files or directory trees). */
 const CI_CONFIG_PATHS = [".github/workflows", ".gitlab-ci.yml", ".circleci", "azure-pipelines.yml"];
 const LOCKFILE_NAMES = new Set([
@@ -82,13 +97,136 @@ function manifestZoneTargets(root) {
     }
     return [...zones].sort().map((z) => rootJoin(root, z));
 }
-export function buildCagePlan(root) {
+/** `rel` equals `base` or lies inside it. */
+function underPath(rel, base) {
+    return rel === base || rel.startsWith(`${base}/`);
+}
+function targetRel(plan, t) {
+    const rel = toPosixRel(plan.root, t.abs);
+    return rel.startsWith("..") ? null : rel;
+}
+function stricter(a, b) {
+    return a && (a.mode === "revert" || b.mode === "report") ? a : b;
+}
+function isOverridden(plan, rel) {
+    return plan.overrides.some((o) => underPath(rel, o));
+}
+/**
+ * The strictest rule for a root-relative path (revert beats report), then `--allow-override`.
+ * Shared by the snapshot, override validation and the push guard so all three agree.
+ */
+export function classifyCagePath(plan, rel, opts = {}) {
+    let hit = null;
+    for (const t of plan.targets) {
+        const base = targetRel(plan, t);
+        if (base !== null && underPath(rel, base))
+            hit = stricter(hit, { rule: t.rule, mode: t.mode, overridden: false });
+    }
+    const byName = cageBasenameRule(path.posix.basename(rel));
+    if (byName)
+        hit = stricter(hit, { rule: byName, mode: CAGE_RULE_MODES[byName], overridden: false });
+    for (const g of plan.globs) {
+        if (g.re.test(rel))
+            hit = stricter(hit, { rule: "cage_protect", mode: g.mode, overridden: false });
+    }
+    return applyCageOverride(plan, rel, hit, opts.overrides !== false);
+}
+/** Downgrade a revert rule to report when the path is overridden; harness rules never are. */
+export function applyCageOverride(plan, rel, hit, enabled = true) {
+    if (!enabled || !hit || hit.mode !== "revert" || NON_OVERRIDABLE_RULES.has(hit.rule))
+        return hit;
+    return isOverridden(plan, rel) ? { ...hit, mode: "report", overridden: true } : hit;
+}
+function overrideError(message) {
+    return new GantryUserError("GXT_CAGE_OVERRIDE_INVALID", `cage: --allow-override ${message}`, undefined, 2);
+}
+function overlaps(a, b) {
+    return underPath(a, b) || underPath(b, a);
+}
+/** Reject overrides that touch harness rules or that match no revert target; returns them normalized. */
+function validateOverrides(plan, raw) {
+    const out = new Set();
+    for (const r of raw) {
+        const o = normalizeCageRelPath(r);
+        if (!o)
+            throw overrideError(`${r}: expected a root-relative path without ".." or a leading "/"`);
+        const harness = plan.targets.find((t) => {
+            const base = targetRel(plan, t);
+            return NON_OVERRIDABLE_RULES.has(t.rule) && base !== null && overlaps(o, base);
+        });
+        if (harness)
+            throw overrideError(`${o}: ${harness.rule} rules cannot be overridden`);
+        const direct = classifyCagePath(plan, o, { overrides: false })?.mode === "revert";
+        const parent = plan.targets.some((t) => {
+            const base = targetRel(plan, t);
+            return t.mode === "revert" && base !== null && underPath(base, o);
+        });
+        if (!direct && !parent)
+            throw overrideError(`${o}: matches no protected revert target`);
+        out.add(o);
+    }
+    return [...out].sort();
+}
+/** Report mode on a path a built-in rule already reverts would read as a relaxation; refuse it. */
+function assertNoBuiltinDowngrade(plan, value) {
+    const hit = classifyCagePath(plan, value, { overrides: false });
+    if (hit && hit.mode === "revert" && cageRuleSource(hit.rule) === "builtin") {
+        throw new GantryUserError("GXT_CAGE_CONFIG_INVALID", `cage: ${CAGE_CONFIG_FILE}: mode: report on ${value} would weaken the built-in ${hit.rule} rule`, "Relax a built-in rule for one run with --allow-override <path>.", 2);
+    }
+}
+function addConfigTargets(plan, root) {
+    const config = loadCageConfig(root);
+    for (const e of config.entries) {
+        if (e.kind === "path" && e.mode === "report")
+            assertNoBuiltinDowngrade(plan, e.value);
+        if (e.kind === "path") {
+            plan.targets.push({ abs: rootJoin(root, e.value), rule: "cage_protect", mode: e.mode, source: "cage_yaml" });
+        }
+        else {
+            plan.globs.push({ pattern: e.value, re: cageGlobToRegExp(e.value), mode: e.mode, source: "cage_yaml" });
+        }
+    }
+    plan.config = {
+        present: config.present,
+        entries: config.entries.length,
+        committed: config.present ? cageConfigCommitted(root) : null,
+    };
+    return config.entries.length;
+}
+function builtinTarget(abs, rule) {
+    return { abs, rule, mode: CAGE_RULE_MODES[rule], source: cageRuleSource(rule) };
+}
+/**
+ * Resolve the session's protected set. An invalid manifest, `.cage.yaml` or override throws, so cage
+ * fails closed before the wrapped command runs.
+ */
+export function buildCagePlan(root, opts = {}) {
     const zones = manifestZoneTargets(root);
-    const targets = [
-        ...CI_CONFIG_PATHS.map((rel) => ({ abs: rootJoin(root, rel), rule: "ci_config" })),
-        ...gitControlTargets(root).map((abs) => ({ abs, rule: "git_control" })),
-        ...zones.map((abs) => ({ abs, rule: "manifest_forbidden_zone" })),
-    ];
-    return { root, targets, manifestZoneCount: zones.length };
+    const plan = {
+        root,
+        targets: [
+            ...CI_CONFIG_PATHS.map((rel) => builtinTarget(rootJoin(root, rel), "ci_config")),
+            ...gitControlTargets(root).map((abs) => builtinTarget(abs, "git_control")),
+            // Always protected, present or not: an in-session edit is restored and a new file is removed.
+            builtinTarget(rootJoin(root, CAGE_CONFIG_FILE), "cage_config"),
+            ...zones.map((abs) => builtinTarget(abs, "manifest_forbidden_zone")),
+        ],
+        globs: [],
+        overrides: [],
+        manifestZoneCount: zones.length,
+        config: { present: false, entries: 0, committed: null },
+    };
+    addConfigTargets(plan, root);
+    plan.overrides = validateOverrides(plan, opts.overrides ?? []);
+    return plan;
+}
+/** JSON form for the session push guard, so it checks the exact plan the session started with. */
+export function serializeCagePlan(plan) {
+    const out = { ...plan, globs: plan.globs.map((g) => ({ pattern: g.pattern, mode: g.mode, source: g.source })) };
+    return JSON.stringify(out);
+}
+export function parseSerializedCagePlan(json) {
+    const p = JSON.parse(json);
+    return { ...p, globs: p.globs.map((g) => ({ ...g, re: cageGlobToRegExp(g.pattern) })) };
 }
 //# sourceMappingURL=cage-rules.js.map

package/dist/cli/lib/cage/cage-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"cage-rules.js","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAW9C,MAAM,CAAC,MAAM,eAAe,GAA+C;IACzE,SAAS,EAAE,QAAQ;IACnB,OAAO,EAAE,QAAQ;IACjB,WAAW,EAAE,QAAQ;IACrB,sFAAsF;IACtF,QAAQ,EAAE,QAAQ;IAClB,uBAAuB,EAAE,QAAQ;CAClC,CAAC;AAEF,yDAAyD;AACzD,MAAM,eAAe,GAAG,CAAC,mBAAmB,EAAE,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,CAAU,CAAC;AAE7G,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,mBAAmB;IACnB,qBAAqB;IACrB,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,WAAW;IACX,YAAY;IACZ,aAAa;IACb,cAAc;IACd,SAAS;IACT,QAAQ;IACR,cAAc;IACd,eAAe;CAChB,CAAC,CAAC;AAEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC;IAC9D,cAAc;IACd,MAAM;IACN,OAAO;IACP,MAAM;IACN,aAAa;CACd,CAAC,CAAC;AAcH,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/F,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IAChD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,QAAgB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,IAAc;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,wBAAwB,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC;AAED,qFAAqF;AACrF,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9D,IAAI,WAAW;QAAE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACvC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5D,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,eAAe,IAAI,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC9E,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAiB;QAC5B,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,WAAoB,EAAE,CAAC,CAAC;QAC3F,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,aAAsB,EAAE,CAAC,CAAC;QAChF,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,yBAAkC,EAAE,CAAC,CAAC;KAC3E,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"cage-rules.js","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-rules.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/cage/cage-run.d.ts

@@ -10,12 +10,32 @@ export interface CageRunOptions {
     reportOnly?: boolean;
     maxFileBytes?: number;
     maxTotalBytes?: number;
+    /** Live restore while the command runs (default true). */
+    watch?: boolean;
+    watchIntervalMs?: number;
+    /** Session pre-push guard for git run by the caged command (default true inside a git work tree). */
+    pushGuard?: boolean;
+    /** Root-relative paths whose revert rules are downgraded to report for this run (`--allow-override`). */
+    allowOverride?: readonly string[];
+    /** Baseline caps; defaults {@link CAGE_MAX_TARGETS} and {@link CAGE_MAX_SCAN_BYTES}. */
+    maxTargets?: number;
+    maxScanBytes?: number;
+    /** Called once before the command starts, e.g. to print where the session log is. */
+    onStart?: (info: {
+        sessionLog: string | null;
+        protectedFiles: number;
+        watch: boolean;
+        overrides: string[];
+        configCommitted: boolean | null;
+    }) => void;
+    bell?: () => void;
 }
 /** Zero-config root: the enclosing git work tree when there is one, otherwise the directory itself. */
 export declare function resolveCageRoot(cwd: string): string;
 /**
- * Snapshot the protected set, run the command, diff, and revert protected changes.
- * Bytes stay in memory only; nothing is written outside the restored paths.
+ * Snapshot the protected set, run the command (restoring protected changes live unless `watch: false`),
+ * diff once more at exit, and restore what is left. Bytes stay in memory; the session log and the
+ * temporary hooks dir live in the OS temp dir, never in the repository.
  */
 export declare function runCage(opts: CageRunOptions): Promise<CageReport>;
 //# sourceMappingURL=cage-run.d.ts.map

package/dist/cli/lib/cage/cage-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cage-run.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-run.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMpE,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAC3D,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA2BvE"}
+{"version":3,"file":"cage-run.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cage/cage-run.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAsBpE,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAC3D,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qGAAqG;IACrG,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yGAAyG;IACzG,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,OAAO,CAAC;QACf,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,eAAe,EAAE,OAAO,GAAG,IAAI,CAAC;KACjC,KAAK,IAAI,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAkFD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAkCvE"}