@prestyj/cli 5.10.0 → 5.11.0

package/dist/core/run-journal.test.js

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { RunLifecycle } from "./run-lifecycle.js";
+import { SessionManager, RUN_STARTED_CUSTOM_KIND, RUN_FINISHED_CUSTOM_KIND, } from "./session-manager.js";
+function recordingJournal() {
+    const calls = [];
+    return {
+        calls,
+        writer: {
+            started: (generation) => calls.push(`start:${generation}`),
+            finished: (generation, outcome) => calls.push(`finish:${generation}:${outcome}`),
+        },
+    };
+}
+function startedEntry(generation, afterMessageCount = 0) {
+    return {
+        type: "custom",
+        kind: RUN_STARTED_CUSTOM_KIND,
+        id: `s${generation}`,
+        parentId: null,
+        timestamp: "2026-07-29T10:00:00.000Z",
+        data: {
+            version: 1,
+            generation,
+            startedAt: "2026-07-29T10:00:00.000Z",
+            afterMessageCount,
+        },
+    };
+}
+function finishedEntry(generation, outcome) {
+    return {
+        type: "custom",
+        kind: RUN_FINISHED_CUSTOM_KIND,
+        id: `f${generation}`,
+        parentId: null,
+        timestamp: "2026-07-29T10:01:00.000Z",
+        data: { version: 1, generation, outcome },
+    };
+}
+describe("RunLifecycle journalling", () => {
+    it("writes a matched pair for a clean run", () => {
+        const { writer, calls } = recordingJournal();
+        const lifecycle = new RunLifecycle(undefined, writer);
+        const lease = lifecycle.begin(vi.fn());
+        lifecycle.settle(lease.generation);
+        expect(calls).toEqual([`start:${lease.generation}`, `finish:${lease.generation}:completed`]);
+    });
+    it("records a failed run as failed", () => {
+        const { writer, calls } = recordingJournal();
+        const lifecycle = new RunLifecycle(undefined, writer);
+        const lease = lifecycle.begin(vi.fn());
+        lifecycle.settle(lease.generation, "failed");
+        expect(calls).toEqual([`start:${lease.generation}`, `finish:${lease.generation}:failed`]);
+    });
+    it("records a cancelled run as aborted regardless of the caller's outcome", async () => {
+        const { writer, calls } = recordingJournal();
+        const lifecycle = new RunLifecycle(undefined, writer);
+        const lease = lifecycle.begin(vi.fn());
+        void lifecycle.cancel(1000);
+        await Promise.resolve();
+        lifecycle.settle(lease.generation, "completed");
+        expect(calls).toEqual([`start:${lease.generation}`, `finish:${lease.generation}:aborted`]);
+    });
+    it("does not let a stale generation close a newer run's journal", () => {
+        const { writer, calls } = recordingJournal();
+        const lifecycle = new RunLifecycle(undefined, writer);
+        const first = lifecycle.begin(vi.fn());
+        lifecycle.settle(first.generation);
+        const second = lifecycle.begin(vi.fn());
+        // The stale settle must be a no-op — not a finish for generation 2.
+        expect(lifecycle.settle(first.generation)).toEqual({ settled: false, cancelled: false });
+        expect(calls).toEqual([`start:1`, `finish:1:completed`, `start:2`]);
+        lifecycle.settle(second.generation);
+        expect(calls.at(-1)).toBe("finish:2:completed");
+    });
+});
+describe("run journal reconstruction", () => {
+    const manager = new SessionManager(path.join(os.tmpdir(), "gg-run-journal-unused"));
+    it("pairs each start with its own generation's finish", () => {
+        const entries = [
+            startedEntry(1, 0),
+            finishedEntry(1, "completed"),
+            startedEntry(2, 4),
+            finishedEntry(2, "aborted"),
+        ];
+        expect(manager.getRunJournal(entries)).toEqual([
+            {
+                generation: 1,
+                startedAt: "2026-07-29T10:00:00.000Z",
+                afterMessageCount: 0,
+                outcome: "completed",
+            },
+            {
+                generation: 2,
+                startedAt: "2026-07-29T10:00:00.000Z",
+                afterMessageCount: 4,
+                outcome: "aborted",
+            },
+        ]);
+        expect(manager.getUnfinishedRuns(entries)).toEqual([]);
+    });
+    it("detects a truncated log as unfinished exactly once", () => {
+        // The crash shape: the last run opened and the file just stops.
+        const entries = [startedEntry(1), finishedEntry(1, "completed"), startedEntry(2, 6)];
+        const unfinished = manager.getUnfinishedRuns(entries);
+        expect(unfinished).toHaveLength(1);
+        expect(unfinished[0]).toMatchObject({ generation: 2, afterMessageCount: 6 });
+    });
+    it("counts a duplicated start line once, not twice", () => {
+        // A replayed/re-persisted log must not manufacture phantom crashed runs.
+        const entries = [startedEntry(3), startedEntry(3), startedEntry(3)];
+        expect(manager.getUnfinishedRuns(entries)).toHaveLength(1);
+    });
+    it("detects a crash in a RESUMED session, where generations restart at 1", () => {
+        // Generations are not unique across a session file: RunLifecycle counts from
+        // zero per instance and a resumed session builds a fresh one, so the first
+        // run after every app restart is generation 1 again.
+        //
+        // Treating the reused number as a duplicate made a crash-after-restart
+        // invisible — exactly the case this journal exists to catch.
+        const entries = [
+            startedEntry(1, 0),
+            finishedEntry(1, "completed"),
+            // App restarts, same session resumed, generation 1 again — then dies.
+            startedEntry(1, 4),
+        ];
+        expect(manager.getRunJournal(entries)).toHaveLength(2);
+        const unfinished = manager.getUnfinishedRuns(entries);
+        expect(unfinished).toHaveLength(1);
+        // The SECOND run is the crashed one; the first stays completed.
+        expect(unfinished[0]).toMatchObject({ generation: 1, afterMessageCount: 4 });
+    });
+    it("closes only the open run when a generation is reused", () => {
+        // gen 1 opens, a replayed start line repeats it, then one finish arrives.
+        // The finish must close the single open run and leave nothing dangling.
+        const entries = [startedEntry(1, 0), startedEntry(1, 6), finishedEntry(1, "completed")];
+        expect(manager.getRunJournal(entries)).toHaveLength(1);
+        expect(manager.getUnfinishedRuns(entries)).toEqual([]);
+    });
+    it("ignores a finish whose start was lost and malformed payloads", () => {
+        const orphan = finishedEntry(9, "completed");
+        const malformed = {
+            type: "custom",
+            kind: RUN_STARTED_CUSTOM_KIND,
+            id: "bad",
+            parentId: null,
+            timestamp: "2026-07-29T10:00:00.000Z",
+            data: { version: 2, generation: "not-a-number" },
+        };
+        expect(manager.getRunJournal([orphan, malformed])).toEqual([]);
+    });
+});
+describe("run journal on disk", () => {
+    it("round-trips through a real session file", async () => {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), "gg-run-journal-"));
+        try {
+            const manager = new SessionManager(dir);
+            const session = await manager.create(process.cwd(), "anthropic", "claude-test");
+            await manager.appendRunStarted(session.path, {
+                version: 1,
+                generation: 1,
+                startedAt: "2026-07-29T10:00:00.000Z",
+                afterMessageCount: 2,
+            });
+            await manager.appendRunFinished(session.path, {
+                version: 1,
+                generation: 1,
+                outcome: "completed",
+            });
+            // Second run never closes — the process died.
+            await manager.appendRunStarted(session.path, {
+                version: 1,
+                generation: 2,
+                startedAt: "2026-07-29T10:05:00.000Z",
+                afterMessageCount: 5,
+            });
+            const loaded = await manager.load(session.path);
+            expect(manager.getRunJournal(loaded.entries).map((r) => r.outcome)).toEqual([
+                "completed",
+                undefined,
+            ]);
+            const unfinished = manager.getUnfinishedRuns(loaded.entries);
+            expect(unfinished).toHaveLength(1);
+            expect(unfinished[0].generation).toBe(2);
+            // Journal entries are off-DAG, so they never enter the model's context.
+            expect(manager.getMessages(loaded.entries, loaded.header.leafId)).toEqual([]);
+        }
+        finally {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=run-journal.test.js.map

package/dist/core/run-journal.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-journal.test.js","sourceRoot":"","sources":["../../src/core/run-journal.test.ts"],"names":[],"mappings":"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"}

package/dist/core/run-lifecycle.d.ts

@@ -1,4 +1,17 @@
+import type { RunOutcome } from "./session-manager.js";
 export type RunState = "idle" | "running" | "cancelling";
+/**
+ * Durable record of run boundaries. `RunLifecycle` already owns generation
+ * identity, so hanging the journal off it makes the on-disk pair inherit that
+ * generation-safety for free — a stale run cannot close a newer one's entry.
+ *
+ * Both hooks are fire-and-forget: journalling must never delay a run or fail
+ * one. Implementations swallow their own write errors.
+ */
+export interface RunJournalWriter {
+    started(generation: number): void;
+    finished(generation: number, outcome: RunOutcome): void;
+}
 export type CancelResult = {
     status: "cancelled";
     generation: number;
@@ -19,17 +32,23 @@ export declare class RunBusyError extends Error {
 /** Generation-safe ownership and acknowledged bounded cancellation. */
 export declare class RunLifecycle {
     private readonly onStateChange?;
+    private readonly journal?;
     private currentState;
     private nextGeneration;
     private active?;
-    constructor(onStateChange?: ((state: RunState) => void) | undefined);
+    constructor(onStateChange?: ((state: RunState) => void) | undefined, journal?: RunJournalWriter | undefined);
     get state(): RunState;
     get running(): boolean;
     get generation(): number;
     begin(abort: () => void): RunLease;
     isCancellationRequested(generation: number): boolean;
-    /** Settle only the matching owner; stale generations cannot release a new run. */
-    settle(generation: number): {
+    /**
+     * Settle only the matching owner; stale generations cannot release a new run.
+     *
+     * `outcome` defaults to `completed`; a cancelled run always records `aborted`
+     * regardless, since cancellation is the authoritative signal here.
+     */
+    settle(generation: number, outcome?: RunOutcome): {
         settled: boolean;
         cancelled: boolean;
     };

package/dist/core/run-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-lifecycle.d.ts","sourceRoot":"","sources":["../../src/core/run-lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;AAEzD,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD,qBAAa,YAAa,SAAQ,KAAK;gBACzB,KAAK,EAAE,QAAQ;CAI5B;AAED,uEAAuE;AACvE,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAJ3C,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAY;gBAEE,aAAa,CAAC,GAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,aAAA;IAEtE,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,KAAK,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,QAAQ;IAkBlC,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIpD,kFAAkF;IAClF,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAYpE,4EAA4E;IAC5E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgChD,OAAO,CAAC,QAAQ;CAKjB"}
+{"version":3,"file":"run-lifecycle.d.ts","sourceRoot":"","sources":["../../src/core/run-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CACzD;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD,qBAAa,YAAa,SAAQ,KAAK;gBACzB,KAAK,EAAE,QAAQ;CAI5B;AAED,uEAAuE;AACvE,qBAAa,YAAY;IAMrB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAN3B,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAY;gBAGR,aAAa,CAAC,GAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,aAAA,EACzC,OAAO,CAAC,EAAE,gBAAgB,YAAA;IAG7C,IAAI,KAAK,IAAI,QAAQ,CAEpB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,KAAK,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,QAAQ;IAmBlC,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIpD;;;;;OAKG;IACH,MAAM,CACJ,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,UAAwB,GAChC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAa3C,4EAA4E;IAC5E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgChD,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/core/run-lifecycle.js

@@ -7,11 +7,13 @@ export class RunBusyError extends Error {
 /** Generation-safe ownership and acknowledged bounded cancellation. */
 export class RunLifecycle {
     onStateChange;
+    journal;
     currentState = "idle";
     nextGeneration = 0;
     active;
-    constructor(onStateChange) {
+    constructor(onStateChange, journal) {
         this.onStateChange = onStateChange;
+        this.journal = journal;
     }
     get state() {
         return this.currentState;
@@ -38,13 +40,19 @@ export class RunLifecycle {
             resolveSettlement,
         };
         this.setState("running");
+        this.journal?.started(generation);
         return { generation };
     }
     isCancellationRequested(generation) {
         return this.active?.generation === generation && this.active.cancelRequested;
     }
-    /** Settle only the matching owner; stale generations cannot release a new run. */
-    settle(generation) {
+    /**
+     * Settle only the matching owner; stale generations cannot release a new run.
+     *
+     * `outcome` defaults to `completed`; a cancelled run always records `aborted`
+     * regardless, since cancellation is the authoritative signal here.
+     */
+    settle(generation, outcome = "completed") {
         const active = this.active;
         if (!active || active.generation !== generation) {
             return { settled: false, cancelled: false };
@@ -53,6 +61,7 @@ export class RunLifecycle {
         this.active = undefined;
         this.setState("idle");
         active.resolveSettlement();
+        this.journal?.finished(generation, cancelled ? "aborted" : outcome);
         return { settled: true, cancelled };
     }
     /** Abort once, then acknowledge only after the owning operation settles. */

package/dist/core/run-lifecycle.js.map

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

package/dist/core/sandbox-domains.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Default network allowlist for the OS command sandbox.
+ *
+ * The sandbox is allowlist-only (a bare `*` is rejected), so shipping it on by
+ * default is only viable if ordinary development still works untouched. These
+ * are the hosts mainstream toolchains actually contact for dependency
+ * resolution, source checkout and registry auth — nothing that reads user data.
+ *
+ * Deliberately excluded: arbitrary app/API hosts, telemetry endpoints and
+ * URL shorteners. A project that needs one adds it once in Settings, which is
+ * the moment the boundary earns its keep.
+ */
+export declare const DEFAULT_ALLOWED_DOMAINS: readonly string[];
+//# sourceMappingURL=sandbox-domains.d.ts.map

package/dist/core/sandbox-domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-domains.d.ts","sourceRoot":"","sources":["../../src/core/sandbox-domains.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAwEpD,CAAC"}

package/dist/core/sandbox-domains.js

@@ -0,0 +1,76 @@
+/**
+ * Default network allowlist for the OS command sandbox.
+ *
+ * The sandbox is allowlist-only (a bare `*` is rejected), so shipping it on by
+ * default is only viable if ordinary development still works untouched. These
+ * are the hosts mainstream toolchains actually contact for dependency
+ * resolution, source checkout and registry auth — nothing that reads user data.
+ *
+ * Deliberately excluded: arbitrary app/API hosts, telemetry endpoints and
+ * URL shorteners. A project that needs one adds it once in Settings, which is
+ * the moment the boundary earns its keep.
+ */
+export const DEFAULT_ALLOWED_DOMAINS = [
+    // ── Source hosting (git clone/fetch/push over HTTPS) ──
+    "github.com",
+    "*.github.com",
+    "*.githubusercontent.com",
+    "gitlab.com",
+    "*.gitlab.com",
+    "bitbucket.org",
+    "*.bitbucket.org",
+    "codeberg.org",
+    // ── JavaScript ──
+    "registry.npmjs.org",
+    "*.npmjs.org",
+    "registry.yarnpkg.com",
+    "*.yarnpkg.com",
+    "jsr.io",
+    "deno.land",
+    "*.deno.land",
+    "unpkg.com",
+    "cdn.jsdelivr.net",
+    "*.jsdelivr.net",
+    "cdnjs.cloudflare.com",
+    // ── Python ──
+    "pypi.org",
+    "*.pypi.org",
+    "files.pythonhosted.org",
+    "*.pythonhosted.org",
+    // ── Go (module proxy + checksum database) ──
+    "proxy.golang.org",
+    "sum.golang.org",
+    "*.golang.org",
+    "storage.googleapis.com",
+    // ── Rust ──
+    "crates.io",
+    "*.crates.io",
+    "static.rust-lang.org",
+    "*.rust-lang.org",
+    // ── Ruby ──
+    "rubygems.org",
+    "*.rubygems.org",
+    // ── JVM ──
+    "repo1.maven.org",
+    "*.maven.org",
+    "repo.maven.apache.org",
+    "plugins.gradle.org",
+    "*.gradle.org",
+    // ── PHP ──
+    "packagist.org",
+    "*.packagist.org",
+    // ── .NET ──
+    "api.nuget.org",
+    "*.nuget.org",
+    // ── Containers ──
+    "docker.io",
+    "*.docker.io",
+    "*.docker.com",
+    "ghcr.io",
+    "quay.io",
+    "registry.k8s.io",
+    // ── macOS/Linux toolchain installers ──
+    "formulae.brew.sh",
+    "*.brew.sh",
+];
+//# sourceMappingURL=sandbox-domains.js.map

package/dist/core/sandbox-domains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-domains.js","sourceRoot":"","sources":["../../src/core/sandbox-domains.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,yDAAyD;IACzD,YAAY;IACZ,cAAc;IACd,yBAAyB;IACzB,YAAY;IACZ,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,cAAc;IAEd,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,sBAAsB;IACtB,eAAe;IACf,QAAQ;IACR,WAAW;IACX,aAAa;IACb,WAAW;IACX,kBAAkB;IAClB,gBAAgB;IAChB,sBAAsB;IAEtB,eAAe;IACf,UAAU;IACV,YAAY;IACZ,wBAAwB;IACxB,oBAAoB;IAEpB,8CAA8C;IAC9C,kBAAkB;IAClB,gBAAgB;IAChB,cAAc;IACd,wBAAwB;IAExB,aAAa;IACb,WAAW;IACX,aAAa;IACb,sBAAsB;IACtB,iBAAiB;IAEjB,aAAa;IACb,cAAc;IACd,gBAAgB;IAEhB,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,uBAAuB;IACvB,oBAAoB;IACpB,cAAc;IAEd,YAAY;IACZ,eAAe;IACf,iBAAiB;IAEjB,aAAa;IACb,eAAe;IACf,aAAa;IAEb,mBAAmB;IACnB,WAAW;IACX,aAAa;IACb,cAAc;IACd,SAAS;IACT,SAAS;IACT,iBAAiB;IAEjB,yCAAyC;IACzC,kBAAkB;IAClB,WAAW;CACZ,CAAC"}

package/dist/core/sandbox-feedback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Turn raw OS-sandbox denials into guidance the model can act on.
+ *
+ * A blocked command otherwise surfaces as inscrutable tool noise ("CONNECT
+ * tunnel failed, response 403", "Operation not permitted"), which the model
+ * tends to retry verbatim. Naming the boundary and the one-step fix is what
+ * turns a dead end into a recoverable turn.
+ */
+export interface SandboxDenialNote {
+    kind: "network" | "filesystem";
+    note: string;
+}
+/**
+ * Inspect finished command output for a sandbox denial.
+ *
+ * @param output   Combined stdout/stderr as returned to the model.
+ * @param sandboxed Whether this command actually ran isolated.
+ */
+export declare function describeSandboxDenial(output: string, sandboxed: boolean): SandboxDenialNote | null;
+/** Append the denial note to command output when one applies. */
+export declare function annotateSandboxDenial(output: string, sandboxed: boolean): string;
+//# sourceMappingURL=sandbox-feedback.d.ts.map

package/dist/core/sandbox-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-feedback.d.ts","sourceRoot":"","sources":["../../src/core/sandbox-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA2BH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CA6B1B;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAGhF"}

package/dist/core/sandbox-feedback.js

@@ -0,0 +1,69 @@
+/**
+ * Turn raw OS-sandbox denials into guidance the model can act on.
+ *
+ * A blocked command otherwise surfaces as inscrutable tool noise ("CONNECT
+ * tunnel failed, response 403", "Operation not permitted"), which the model
+ * tends to retry verbatim. Naming the boundary and the one-step fix is what
+ * turns a dead end into a recoverable turn.
+ */
+/** SRT's proxy rejection, plus how common clients report it. */
+const NETWORK_DENIAL = [
+    "blocked-by-allowlist",
+    "Connection blocked by network allowlist",
+    "CONNECT tunnel failed, response 403",
+];
+const FILESYSTEM_DENIAL = ["Operation not permitted", "operation not permitted", "EPERM"];
+/** Hosts the command tried to reach, best-effort, for a precise suggestion. */
+function extractHosts(output) {
+    const hosts = new Set();
+    const patterns = [
+        /(?:CONNECT|to)\s+([a-z0-9.-]+\.[a-z]{2,})(?::\d+)?/gi,
+        /https?:\/\/([a-z0-9.-]+\.[a-z]{2,})/gi,
+    ];
+    for (const pattern of patterns) {
+        for (const match of output.matchAll(pattern)) {
+            const host = match[1]?.toLowerCase();
+            if (host && !host.endsWith(".local"))
+                hosts.add(host);
+        }
+    }
+    return [...hosts].slice(0, 3);
+}
+/**
+ * Inspect finished command output for a sandbox denial.
+ *
+ * @param output   Combined stdout/stderr as returned to the model.
+ * @param sandboxed Whether this command actually ran isolated.
+ */
+export function describeSandboxDenial(output, sandboxed) {
+    if (!sandboxed || !output)
+        return null;
+    if (NETWORK_DENIAL.some((marker) => output.includes(marker))) {
+        const hosts = extractHosts(output);
+        const target = hosts.length > 0 ? hosts.join(", ") : "that host";
+        return {
+            kind: "network",
+            note: `\n\n[Sandbox] Network blocked: ${target} is not an approved destination. ` +
+                `Common package registries and git hosts are approved already, so double-check the ` +
+                `address first. If the user genuinely needs it, ask them to add it under ` +
+                `Settings → Command safety → Approved sites (or turn command safety off).`,
+        };
+    }
+    if (FILESYSTEM_DENIAL.some((marker) => output.includes(marker))) {
+        return {
+            kind: "filesystem",
+            note: `\n\n[Sandbox] Write blocked: that path is either outside this project or a ` +
+                `protected file (.env). Prefer a path inside the project, or use the write ` +
+                `tool if the user asked for that exact file. If they genuinely need shell ` +
+                `writes elsewhere, ask them to enable Settings → Command safety → Allow ` +
+                `changes outside the project.`,
+        };
+    }
+    return null;
+}
+/** Append the denial note to command output when one applies. */
+export function annotateSandboxDenial(output, sandboxed) {
+    const denial = describeSandboxDenial(output, sandboxed);
+    return denial ? `${output}${denial.note}` : output;
+}
+//# sourceMappingURL=sandbox-feedback.js.map

package/dist/core/sandbox-feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-feedback.js","sourceRoot":"","sources":["../../src/core/sandbox-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gEAAgE;AAChE,MAAM,cAAc,GAAG;IACrB,sBAAsB;IACtB,yCAAyC;IACzC,qCAAqC;CACtC,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,yBAAyB,EAAE,yBAAyB,EAAE,OAAO,CAAC,CAAC;AAE1F,+EAA+E;AAC/E,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,QAAQ,GAAG;QACf,sDAAsD;QACtD,uCAAuC;KACxC,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;YACrC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAOD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,SAAkB;IAElB,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;QACjE,OAAO;YACL,IAAI,EAAE,SAAS;YACf,IAAI,EACF,kCAAkC,MAAM,mCAAmC;gBAC3E,oFAAoF;gBACpF,0EAA0E;gBAC1E,0EAA0E;SAC7E,CAAC;IACJ,CAAC;IAED,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,IAAI,EACF,6EAA6E;gBAC7E,4EAA4E;gBAC5E,2EAA2E;gBAC3E,yEAAyE;gBACzE,8BAA8B;SACjC,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,SAAkB;IACtE,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxD,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACrD,CAAC"}

package/dist/core/sandbox-feedback.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandbox-feedback.test.d.ts.map

package/dist/core/sandbox-feedback.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-feedback.test.d.ts","sourceRoot":"","sources":["../../src/core/sandbox-feedback.test.ts"],"names":[],"mappings":""}

package/dist/core/sandbox-feedback.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { annotateSandboxDenial, describeSandboxDenial } from "./sandbox-feedback.js";
+describe("describeSandboxDenial", () => {
+    it("names the blocked host and the one place a user can approve it", () => {
+        const output = "Exit code: 0\ncurl: (56) CONNECT tunnel failed, response 403\nCONNECT api.example.com:443";
+        const denial = describeSandboxDenial(output, true);
+        expect(denial?.kind).toBe("network");
+        expect(denial?.note).toContain("api.example.com");
+        expect(denial?.note).toContain("Approved sites");
+        // The model must not be told to silently give up or disable protection first.
+        expect(denial?.note).toContain("ask them");
+    });
+    it("points a blocked write back inside the project", () => {
+        const output = "touch: /Users/x/secret: Operation not permitted";
+        const denial = describeSandboxDenial(output, true);
+        expect(denial?.kind).toBe("filesystem");
+        expect(denial?.note).toContain("outside this project");
+    });
+    it("stays silent for ordinary failures and for unsandboxed commands", () => {
+        expect(describeSandboxDenial("Exit code: 1\nnpm ERR! missing script: buil", true)).toBeNull();
+        // Same text, but the command never ran isolated — the sandbox cannot be the cause.
+        expect(describeSandboxDenial("Operation not permitted", false)).toBeNull();
+    });
+    it("annotates output without discarding the original text", () => {
+        const output = "Exit code: 0\nConnection blocked by network allowlist";
+        const annotated = annotateSandboxDenial(output, true);
+        expect(annotated.startsWith(output)).toBe(true);
+        expect(annotated).toContain("[Sandbox]");
+        expect(annotateSandboxDenial(output, false)).toBe(output);
+    });
+});
+//# sourceMappingURL=sandbox-feedback.test.js.map

package/dist/core/sandbox-feedback.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-feedback.test.js","sourceRoot":"","sources":["../../src/core/sandbox-feedback.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAErF,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,MAAM,GACV,2FAA2F,CAAC;QAE9F,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEnD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAClD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QACjD,8EAA8E;QAC9E,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,MAAM,GAAG,iDAAiD,CAAC;QAEjE,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEnD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,CAAC,qBAAqB,CAAC,6CAA6C,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC9F,mFAAmF;QACnF,MAAM,CAAC,qBAAqB,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,MAAM,GAAG,uDAAuD,CAAC;QAEvE,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEtD,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QACzC,MAAM,CAAC,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}