@miller-tech/uap 1.172.15 → 1.174.0

package/dist/delivery/bash-sweep.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Turn-end substance sweep for files written through `run_bash`.
+ *
+ * The stub guard covers `write_file` and `edit_file`. `run_bash` bypasses both:
+ * `cat > f <<'EOF' … EOF`, `sed -i` and `python -c "open(...).write(...)"` all
+ * land content without passing through a tool handler. That was recorded as a
+ * known limit when the guard shipped (PR #611) rather than papered over, and
+ * this closes it.
+ *
+ * WHY A SWEEP AND NOT A CHECK IN THE HANDLER
+ * The other run_bash protections work by SNAPSHOTTING a known set — protected
+ * tests, locked contracts, gate configs — and restoring whatever the command
+ * touched. That works because those sets are enumerable up front. The set of
+ * files a shell command might write is not, so there is nothing to snapshot by
+ * name. The sweep instead takes a baseline of the tree at the first command and
+ * compares at turn end, which is the only way to attribute an arbitrary write.
+ *
+ * THE COST MODEL IS INVERTED FROM THE WRITE PATH, AND THAT DRIVES EVERYTHING
+ * On the write path a false positive costs one retry: the write is refused and
+ * the model tries again. Here a false positive touches a file that already
+ * exists, so it costs WORK. Four consequences, each of which an earlier version
+ * of this file got wrong and each of which now has a test:
+ *
+ *  1. Absence of baseline CONTENT never implies absence of the FILE. Existence
+ *     is recorded for every path with no read and no byte budget, so a file the
+ *     content baseline skipped — capped, oversized, unreadable — is still known
+ *     to have existed. Only a path absent from `known` may be treated as created
+ *     this turn. Without that split, a file the baseline had skipped was DELETED
+ *     when the shell shrank it, and on a tree past the cap files the shell never
+ *     touched became deletion candidates.
+ *  2. Nothing the harness has SEEN is destroyed, and nothing leaves the project.
+ *     Every removal and every revert preserves the current content under
+ *     `.uap/bash-sweep-backup/` first, a failed preserve aborts the action, and
+ *     every destination is proven to resolve inside that directory. The limit is
+ *     worth stating precisely, because a broader claim would be false: a revert
+ *     restores the last content the harness AUTHORISED, so if one shell command
+ *     writes real code and a later command in the SAME turn hollows it, the
+ *     intermediate version — which no tool handler ever saw — is not recovered.
+ *     The rejected content is preserved; the unobserved good version is not. `relative()` used to be run through
+ *     `.split('\\')`, which is correct on Windows and WRONG on POSIX where a
+ *     backslash is a legal filename character: one directory entry named
+ *     `..\..\..\..\x.js` produced a traversing key and the sweep wrote and
+ *     RENAMED outside the project root. (Reproduced; test below. The harness
+ *     already documents that the small model mangles paths, so this needed no
+ *     adversary.)
+ *  3. An existing file is only reverted when the change made it STRICTLY WORSE —
+ *     more empty bodies than the content we authorised. A formatter or codemod
+ *     that rewrites an already-stubby file without emptying anything further is
+ *     left alone, because reverting it would be both wrong and unexplainable
+ *     ("your shell command wrote SKELETONS" about `prettier --write`).
+ *  4. Silence must mean "nothing changed", not "we could not look". Coverage
+ *     gaps are reported — but ONLY for files that actually changed. Reporting
+ *     every unreadable path made a single `logo.png` emit a coverage warning on
+ *     every bash turn of every asset-bearing project, into a prompt slot that is
+ *     head-truncated.
+ *
+ * WHAT COUNTS AS THE BASELINE
+ * Per file, the last content this harness knows it authorised: what a guarded
+ * tool wrote this turn if one did, otherwise the content at the first command.
+ * Using "was it written by a guarded tool" as a plain skip would leave a hole —
+ * write the real implementation with write_file, then hollow it out with sed,
+ * and the path is on the allow-list. Comparing against the authorised CONTENT
+ * closes it. A file CREATED this turn is judged on its own content regardless of
+ * authorisation, which closes the mirror hole: the shell writes a skeleton, then
+ * a single edit_file fills one body and the monotone-progress rule — measuring
+ * against the skeleton itself — stamps the rest as authorised.
+ *
+ * SCOPE, STATED PLAINLY
+ * This is a correctness guard against confused generation, not a security
+ * boundary. A model holding a shell can do anything a shell can do, including
+ * removing this check; run_bash is gated on kernel containment for that reason.
+ * The sweep judges SUBSTANCE only — a command that deletes a real file is a
+ * different failure and is not restored here. And a quarantine can leave the
+ * tree in a state neither the model nor the gates have seen: a `main.js` written
+ * by write_file may import a `player.js` the sweep removed. The gates see that
+ * and the note names the repair, which is the intended outcome, but it is a real
+ * intermediate state rather than a clean rollback.
+ */
+export interface SweepLimits {
+    /** Max files whose CONTENT is baselined. Existence is never capped. */
+    maxFiles: number;
+    /** Max total bytes of baselined content. */
+    maxTotalBytes: number;
+    /** Per-file read ceiling; matches the detector's own scan cap. */
+    maxFileBytes: number;
+}
+/**
+ * A delivery target is an application, not a monorepo, so these sit far above
+ * any real project — they exist so a mission pointed at something huge degrades
+ * predictably instead of reading gigabytes inside a turn boundary. Injectable so
+ * tests exercise the capped paths for real rather than setting a flag by hand.
+ */
+export declare const DEFAULT_LIMITS: SweepLimits;
+/** Where displaced content goes. Inside `.uap`, so the sweep never re-walks it. */
+export declare const BACKUP_DIR: string;
+export interface BashSweep {
+    /** False when bash is disabled for the session: no baseline, no sweep. */
+    readonly enabled: boolean;
+    /** Root of both walks. */
+    readonly projectRoot: string;
+    /** Set true once a command has run — the sweep is a no-op until then. */
+    bashRan: boolean;
+    /** Whether the baseline walk has happened (it is lazy). */
+    baselined: boolean;
+    /**
+     * Whether the sweep has already run for this turn. The wrapper calls
+     * finishBashSweep on the success path and again from `finally`; making the
+     * second call a no-op here — rather than relying on the caller to track it —
+     * keeps the double walk out of every bash turn no matter who calls.
+     */
+    swept: boolean;
+    /** Project-relative path -> content a guarded tool wrote this turn. */
+    readonly authorised: Map<string, string>;
+    /** Project-relative path -> content at the first command. May be partial. */
+    readonly baseline: Map<string, string>;
+    /** EVERY path that existed at the first command. Never capped — see doc. */
+    readonly known: Set<string>;
+    /**
+     * Size and mtime of every known path. Two jobs: an unbaselined file's CHANGE
+     * stays visible (so coverage warnings name files that actually moved), and the
+     * sweep can skip re-reading a file that demonstrably did not move — otherwise
+     * it re-reads the entire content baseline on a turn where the shell touched
+     * one file.
+     */
+    readonly statAt: Map<string, {
+        size: number;
+        mtimeMs: number;
+    }>;
+    /** True when the file-count/byte budget cut the content baseline short. */
+    truncated: boolean;
+    readonly limits: SweepLimits;
+}
+export interface SweepOutcome {
+    /** Paths reverted to their authorised content (backed up first). */
+    reverted: string[];
+    /** Paths moved into the backup — they did not exist before the turn. */
+    removed: string[];
+    /** Paths that CHANGED but could not be attributed; left untouched. */
+    uncovered: string[];
+    /** Paths the sweep decided to act on but could not. */
+    failed: string[];
+    /** Model-facing note, '' when there is nothing to say. */
+    note: string;
+}
+/** A sweep that never fires — for callers with bash disabled. */
+export declare function disabledSweep(): BashSweep;
+/**
+ * Arm the sweep for a turn. Deliberately does NOT walk anything.
+ *
+ * The baseline is captured lazily, at the first command, so a bash-enabled
+ * session that does not actually shell out in a given turn pays nothing.
+ * Deferring is safe because of what `authorised` holds: anything that changed
+ * BEFORE the first command can only have come from a guarded tool, and those
+ * writes are recorded by content as they happen.
+ */
+export declare function beginBashSweep(projectRoot: string, enabled: boolean, limits?: SweepLimits): BashSweep;
+/**
+ * Arm for a command: mark that the shell ran, and capture the baseline once.
+ *
+ * Called from the run_bash handler BEFORE the spawn — a command that times out
+ * or is killed may still have written files, and a sweep with nothing to compare
+ * against would be worse than none, reporting "checked" over the messiest case.
+ */
+export declare function armSweepForCommand(sweep: BashSweep): void;
+/** Record what a guarded tool wrote, so a later shell write is distinguishable. */
+export declare function recordAuthorisedWrite(sweep: BashSweep, rel: string, content: string): void;
+/**
+ * Compare the tree against the baseline and undo unattributed stub writes.
+ * Returns an empty outcome when bash never ran, so the common path is a boolean.
+ */
+export declare function finishBashSweep(sweep: BashSweep): SweepOutcome;
+/**
+ * Put the note FIRST — but never ahead of a protocol marker.
+ *
+ * The retry prompt includes the previous output through `truncateHead`, which
+ * keeps the leading 3000 characters, so a note appended after a long turn summary
+ * is exactly the part that gets cut. That argues for prepending.
+ *
+ * Against it: `decodeBudgetStop` only recognises the context-budget marker within
+ * the first 512 characters, and this note routinely exceeds that on its own. A
+ * budget-stopped turn that was also swept would therefore stop being recognised
+ * as budget-stopped — which silently disables the epic controller's rail-sizing
+ * split, on exactly the long shell-using sessions that blow the rail. So when the
+ * output carries that marker, the note goes after the marker's own line: the
+ * marker keeps position 0, and the note is still near the front.
+ */
+export declare function prependSweepNote(output: string, outcome: SweepOutcome): string;
+//# sourceMappingURL=bash-sweep.d.ts.map

package/dist/delivery/bash-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-sweep.d.ts","sourceRoot":"","sources":["../../src/delivery/bash-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AA+DH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,WAI5B,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,UAAU,QAAoC,CAAC;AAE5D,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;CACd;AAOD,iEAAiE;AACjE,wBAAgB,aAAa,IAAI,SAAS,CAczC;AAsGD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,WAA4B,GACnC,SAAS,CAuBX;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAuBzD;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1F;AA+ED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAgH9D;AA+DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAS9E"}