@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/cjs/TestRunner.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The repository's own test invocation, declared once by the host.
+ *
+ * Every repository already knows how to run its tests, and the harness is told
+ * so at setup. What the measured program shows is what happens when that fact
+ * is not a *callable* thing: agents guess labels
+ * (`management_commands.test_flush`, `tests/related_lookup`, `test_axis.py` —
+ * none of which exist), and a guessed label costs a frame each time. Seven such
+ * invocations are documented across the 45 instances.
+ *
+ * So the invocation is a declaration, not a parameter: a caller of the `test`
+ * flow selects *which* tests, never *how* to run them.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer } from "effect";
+import * as StdError from "./StdError.ts";
+/**
+ * The default ref naming a tree as it stood before the agent touched it.
+ *
+ * The engine records the pristine checkout under this ref, so a baseline run
+ * reuses what already exists instead of inventing a second notion of "base".
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const captureBase = "refs/flows/capture-base";
+/**
+ * How this repository runs its tests.
+ *
+ * `cwd` is where the runner runs, and `root` is the host directory holding the
+ * git repository. They differ exactly when the runner runs in a container: the
+ * container sees the repository at `cwd`, the host sees it at `root`, and a
+ * baseline checkout created at `<root>/<name>` is visible to the runner at
+ * `<cwd>/<name>` because it is the same directory under two names.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Runner {
+    /** The runner command line, without any test selection. */
+    readonly command: string;
+    /** Where the runner runs; the container's path when `container` is set. */
+    readonly cwd?: string | undefined;
+    /** The host path of the repository, when it differs from `cwd`. */
+    readonly root?: string | undefined;
+    /** A container to route the run through, via the `Container` transport. */
+    readonly container?: string | undefined;
+    /** Environment the runner needs. */
+    readonly env?: Record<string, string> | undefined;
+    /** The ref whose commit is the pristine base; defaults to {@link captureBase}, then HEAD. */
+    readonly baseRef?: string | undefined;
+    /** False refuses baseline requests before any process runs. */
+    readonly baseline?: false | undefined;
+    /** Default wall-clock budget for one run. */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * The declaration service.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface TestRunner {
+    readonly declared: Effect.Effect<Runner, StdError.StdError>;
+}
+/**
+ * The {@link TestRunner} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export declare const TestRunner: Context.Service<TestRunner, TestRunner>;
+/**
+ * Declares one repository's runner.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (runner: Runner) => TestRunner;
+/**
+ * Declares that this host knows of no runner.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeNoop: () => TestRunner;
+/**
+ * Provides {@link make}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: (runner: Runner) => Layer.Layer<TestRunner>;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerNoop: Layer.Layer<TestRunner>;
+//# sourceMappingURL=TestRunner.d.ts.map

package/dist/cjs/TestRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestRunner.d.ts","sourceRoot":"","sources":["../../src/TestRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,4BAA4B,CAAA;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;CAC5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAA6C,CAAA;AAE5G;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,QAAQ,MAAM,KAAG,UAAiE,CAAA;AAEvG;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,UASxB,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAA4C,CAAA;AAEzG;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAyC,CAAA"}

package/dist/cjs/TestRunner.js

@@ -0,0 +1,54 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TestRunner_exports = {};
+__export(TestRunner_exports, {
+  TestRunner: () => TestRunner,
+  captureBase: () => captureBase,
+  layer: () => layer,
+  layerNoop: () => layerNoop,
+  make: () => make,
+  makeNoop: () => makeNoop
+});
+module.exports = __toCommonJS(TestRunner_exports);
+var import_effect = require("effect");
+var StdError = __toESM(require("./StdError.js"), 1);
+const captureBase = "refs/flows/capture-base";
+const TestRunner = import_effect.Context.Service("@smthrs/std/TestRunner");
+const make = (runner) => TestRunner.of({ declared: import_effect.Effect.succeed(runner) });
+const makeNoop = () => TestRunner.of({
+  declared: import_effect.Effect.fail(
+    new StdError.StdError({
+      code: "provider_unavailable",
+      message: "No test runner is declared for this repository, so there is nothing for the test flow to run. Use bash with the command this project's own documentation gives."
+    })
+  )
+});
+const layer = (runner) => import_effect.Layer.succeed(TestRunner, make(runner));
+const layerNoop = import_effect.Layer.succeed(TestRunner, makeNoop());
+//# sourceMappingURL=TestRunner.js.map

package/dist/cjs/TestRunner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TestRunner.ts"],
+  "sourcesContent": ["/**\n * The repository's own test invocation, declared once by the host.\n *\n * Every repository already knows how to run its tests, and the harness is told\n * so at setup. What the measured program shows is what happens when that fact\n * is not a *callable* thing: agents guess labels\n * (`management_commands.test_flush`, `tests/related_lookup`, `test_axis.py` \u2014\n * none of which exist), and a guessed label costs a frame each time. Seven such\n * invocations are documented across the 45 instances.\n *\n * So the invocation is a declaration, not a parameter: a caller of the `test`\n * flow selects *which* tests, never *how* to run them.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer } from \"effect\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * The default ref naming a tree as it stood before the agent touched it.\n *\n * The engine records the pristine checkout under this ref, so a baseline run\n * reuses what already exists instead of inventing a second notion of \"base\".\n *\n * @category constants\n * @since 1.0.0\n */\nexport const captureBase = \"refs/flows/capture-base\"\n\n/**\n * How this repository runs its tests.\n *\n * `cwd` is where the runner runs, and `root` is the host directory holding the\n * git repository. They differ exactly when the runner runs in a container: the\n * container sees the repository at `cwd`, the host sees it at `root`, and a\n * baseline checkout created at `<root>/<name>` is visible to the runner at\n * `<cwd>/<name>` because it is the same directory under two names.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Runner {\n  /** The runner command line, without any test selection. */\n  readonly command: string\n  /** Where the runner runs; the container's path when `container` is set. */\n  readonly cwd?: string | undefined\n  /** The host path of the repository, when it differs from `cwd`. */\n  readonly root?: string | undefined\n  /** A container to route the run through, via the `Container` transport. */\n  readonly container?: string | undefined\n  /** Environment the runner needs. */\n  readonly env?: Record<string, string> | undefined\n  /** The ref whose commit is the pristine base; defaults to {@link captureBase}, then HEAD. */\n  readonly baseRef?: string | undefined\n  /** False refuses baseline requests before any process runs. */\n  readonly baseline?: false | undefined\n  /** Default wall-clock budget for one run. */\n  readonly timeoutMs?: number | undefined\n}\n\n/**\n * The declaration service.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface TestRunner {\n  readonly declared: Effect.Effect<Runner, StdError.StdError>\n}\n\n/**\n * The {@link TestRunner} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const TestRunner: Context.Service<TestRunner, TestRunner> = Context.Service(\"@smthrs/std/TestRunner\")\n\n/**\n * Declares one repository's runner.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (runner: Runner): TestRunner => TestRunner.of({ declared: Effect.succeed(runner) })\n\n/**\n * Declares that this host knows of no runner.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): TestRunner =>\n  TestRunner.of({\n    declared: Effect.fail(\n      new StdError.StdError({\n        code: \"provider_unavailable\",\n        message:\n          \"No test runner is declared for this repository, so there is nothing for the test flow to run. Use bash with the command this project's own documentation gives.\"\n      })\n    )\n  })\n\n/**\n * Provides {@link make}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer = (runner: Runner): Layer.Layer<TestRunner> => Layer.succeed(TestRunner, make(runner))\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<TestRunner> = Layer.succeed(TestRunner, makeNoop())\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,oBAAuC;AACvC,eAA0B;AAWnB,MAAM,cAAc;AAiDpB,MAAM,aAAsD,sBAAQ,QAAQ,wBAAwB;AAQpG,MAAM,OAAO,CAAC,WAA+B,WAAW,GAAG,EAAE,UAAU,qBAAO,QAAQ,MAAM,EAAE,CAAC;AAQ/F,MAAM,WAAW,MACtB,WAAW,GAAG;AAAA,EACZ,UAAU,qBAAO;AAAA,IACf,IAAI,SAAS,SAAS;AAAA,MACpB,MAAM;AAAA,MACN,SACE;AAAA,IACJ,CAAC;AAAA,EACH;AACF,CAAC;AAQI,MAAM,QAAQ,CAAC,WAA4C,oBAAM,QAAQ,YAAY,KAAK,MAAM,CAAC;AAQjG,MAAM,YAAqC,oBAAM,QAAQ,YAAY,SAAS,CAAC;",
+  "names": []
+}

package/dist/cjs/TreeFingerprint.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The identity of one directory tree, measured where the tree is.
+ *
+ * `@smthrs/agent/WorkspaceObservation` measures the host workspace around
+ * every frame so the loop's mutation accounting is a fact rather than a
+ * claim. A command routed into a container writes to a filesystem that walk
+ * never sees: the SWE-bench rig bind-mounts the checkout into its container,
+ * so a container edit lands on the host too, but a container Harbor or Pier
+ * starts has no such mount, and every edit an agent made there read as an
+ * idle frame. Measured 2026-09-22 on Terminal-Bench 4.0: `read_only_cap`
+ * ended one run after twenty-four frames of container writes, and the claim
+ * judge refused another's completion as "work this run never recorded".
+ *
+ * This module is the same measurement taken inside the container: one POSIX
+ * shell script that lists every kept file under a directory with its size and
+ * modification time, in sorted order, and prints one checksum of the listing.
+ * `bash` runs it through the container transport before and after a
+ * containerised command and reports whether the two answers differ under the
+ * reserved {@link key}. The harness reads that key as a measured write, the
+ * way it reads `invalidProbe` as a measured refusal.
+ *
+ * The same properties as the host walk, and the same stated limits:
+ *
+ * - **Identity, not content.** Size and mtime per file; a rewrite that
+ *   restores both is invisible.
+ * - **Pruning is the signal.** {@link defaultPrune} and
+ *   {@link defaultIgnoreSuffixes} are the one list both measurements use, so
+ *   a derived artifact the host walk skips is skipped here too.
+ * - **A partial listing says so.** The listing stops at {@link maxPaths}, and
+ *   a measurement that stopped there reports `complete: false`; `bash` then
+ *   reports nothing rather than a guess.
+ * - **Every tool it needs is POSIX or busybox.** `find -prune`, `stat -c`,
+ *   `sort`, `head`, `cksum` and `grep -c` are in every Linux base image this
+ *   has been run against, GNU and busybox alike. A container that lacks one
+ *   answers with a non-zero exit, which is read as "unmeasured".
+ *
+ * @since 1.0.0
+ */
+/**
+ * The reserved output key a flow reports a measured write under.
+ *
+ * A wire contract with the harness rather than a shared type, exactly as
+ * `Probe.key` is: `@smthrs/harness` reads this key off a `Schema.Json` result
+ * and must not depend on the tool library to do it. `true` means the tree the
+ * call targeted differed after the call from before it; `false` means it was
+ * measured and held still; absent means it was not measured.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const key = "mutated";
+/**
+ * Directory names never descended into.
+ *
+ * Every entry is a place a tool writes derived state while the run is working:
+ * version-control internals, dependency trees, and the caches Python, Node,
+ * Rust and their test runners keep beside the sources. A run that changes only
+ * these has changed nothing it will be judged on.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const defaultPrune: ReadonlyArray<string>;
+/**
+ * File and directory name suffixes left out of a measurement.
+ *
+ * Compiled output is the case that matters: several SWE-bench projects build
+ * extensions in place, which drops `.so` files next to the `.py` files they
+ * came from. Those move whenever the run executes its test suite, and
+ * counting them would report every probe as an edit.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const defaultIgnoreSuffixes: ReadonlyArray<string>;
+/**
+ * The largest number of files one measurement covers.
+ *
+ * The same bound the host walk uses, for the same reason: a listing that
+ * stopped here covers a prefix chosen by sort order, and a prefix holding
+ * still says nothing about the files being edited outside it.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const maxPaths = 50000;
+/**
+ * One measurement, as {@link parse} reads it off the script's output.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Measurement {
+    /** The checksum of the whole listing; equal for two measurements of an unchanged tree. */
+    readonly digest: string;
+    /** How many files the listing covered. */
+    readonly paths: number;
+    /** Whether the listing covered the whole tree rather than a bounded prefix. */
+    readonly complete: boolean;
+}
+/**
+ * The POSIX shell script that measures the current directory.
+ *
+ * Prints two lines: `cksum`'s `<crc> <bytes>` over the sorted listing, then
+ * the number of listing lines. The listing is capped one past
+ * {@link maxPaths} so the count alone says whether the bound was reached.
+ * Errors from `find` and `stat` are discarded: a path that vanished mid-walk
+ * is movement the next measurement reports, and a file the shell may not
+ * stat is one it could not have measured either way.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const script: (options?: {
+    readonly prune?: ReadonlyArray<string> | undefined;
+    readonly ignoreSuffixes?: ReadonlyArray<string> | undefined;
+}) => string;
+/**
+ * Reads one measurement off the script's standard output.
+ *
+ * `undefined` for anything that is not two well-formed lines: the script did
+ * not run, a tool it needs is missing, or the output was cut. An unmeasured
+ * tree is reported as unmeasured, never as unchanged.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export declare const parse: (stdout: string) => Measurement | undefined;
+/**
+ * Whether two measurements say the tree moved, or nothing at all.
+ *
+ * `true` and `false` are answers; `undefined` is the honest reading whenever
+ * either measurement is absent or bounded, because a prefix that held still
+ * is not a tree that held still.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export declare const moved: (before: Measurement | undefined, after: Measurement | undefined) => boolean | undefined;
+//# sourceMappingURL=TreeFingerprint.d.ts.map

package/dist/cjs/TreeFingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeFingerprint.d.ts","sourceRoot":"","sources":["../../src/TreeFingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG,YAAY,CAAA;AAE5B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAM9C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAUvD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,QAAS,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAKD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,GAAI,UAAS;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACvD,KAAG,MAaR,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,WAAW,GAAG,SAapD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAChB,QAAQ,WAAW,GAAG,SAAS,EAC/B,OAAO,WAAW,GAAG,SAAS,KAC7B,OAAO,GAAG,SAGuB,CAAA"}

package/dist/cjs/TreeFingerprint.js

@@ -0,0 +1,87 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key2 of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key2) && key2 !== except)
+        __defProp(to, key2, { get: () => from[key2], enumerable: !(desc = __getOwnPropDesc(from, key2)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TreeFingerprint_exports = {};
+__export(TreeFingerprint_exports, {
+  defaultIgnoreSuffixes: () => defaultIgnoreSuffixes,
+  defaultPrune: () => defaultPrune,
+  key: () => key,
+  maxPaths: () => maxPaths,
+  moved: () => moved,
+  parse: () => parse,
+  script: () => script
+});
+module.exports = __toCommonJS(TreeFingerprint_exports);
+var Prune = __toESM(require("./internal/Prune.js"), 1);
+const key = "mutated";
+const defaultPrune = [
+  ...Prune.repositoryDirectories,
+  // Build and environment directories a search still reads, since a project
+  // may keep sources under these names, but a measurement leaves out.
+  "venv",
+  "target"
+];
+const defaultIgnoreSuffixes = [
+  ".pyc",
+  ".pyo",
+  ".pyd",
+  ".so",
+  ".o",
+  ".a",
+  ".dylib",
+  ".class",
+  ".egg-info"
+];
+const maxPaths = 5e4;
+const quoted = (name) => `'${name.replaceAll("'", `'\\''`)}'`;
+const script = (options = {}) => {
+  const prune = (options.prune ?? defaultPrune).map((name) => `-name ${quoted(name)}`).join(" -o ");
+  const skipped = (options.ignoreSuffixes ?? defaultIgnoreSuffixes).map((suffix) => `! -name ${quoted(`*${suffix}`)}`).join(" ");
+  return [
+    "set -f",
+    `L=$(find . -xdev \\( ${prune} \\) -prune -o -type f ${skipped} -exec stat -c '%s %Y %n' {} + 2>/dev/null | LC_ALL=C sort | head -n ${maxPaths + 1})`,
+    `printf '%s' "$L" | cksum`,
+    `printf '%s' "$L" | grep -c ''`
+  ].join("\n");
+};
+const parse = (stdout) => {
+  const lines = stdout.trim().split("\n").map((line) => line.trim());
+  if (lines.length !== 2) return void 0;
+  const checksum = /^(\d+) (\d+)$/.exec(lines[0]);
+  const count = /^(\d+)$/.exec(lines[1]);
+  if (checksum === null || count === null) return void 0;
+  const paths = Number(count[1]);
+  const bounded = paths > maxPaths;
+  return {
+    digest: `${checksum[1]}:${checksum[2]}`,
+    paths: bounded ? maxPaths : paths,
+    complete: !bounded
+  };
+};
+const moved = (before, after) => before === void 0 || after === void 0 || !before.complete || !after.complete ? void 0 : before.digest !== after.digest;
+//# sourceMappingURL=TreeFingerprint.js.map

package/dist/cjs/TreeFingerprint.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/TreeFingerprint.ts"],
+  "sourcesContent": ["/**\n * The identity of one directory tree, measured where the tree is.\n *\n * `@smthrs/agent/WorkspaceObservation` measures the host workspace around\n * every frame so the loop's mutation accounting is a fact rather than a\n * claim. A command routed into a container writes to a filesystem that walk\n * never sees: the SWE-bench rig bind-mounts the checkout into its container,\n * so a container edit lands on the host too, but a container Harbor or Pier\n * starts has no such mount, and every edit an agent made there read as an\n * idle frame. Measured 2026-09-22 on Terminal-Bench 4.0: `read_only_cap`\n * ended one run after twenty-four frames of container writes, and the claim\n * judge refused another's completion as \"work this run never recorded\".\n *\n * This module is the same measurement taken inside the container: one POSIX\n * shell script that lists every kept file under a directory with its size and\n * modification time, in sorted order, and prints one checksum of the listing.\n * `bash` runs it through the container transport before and after a\n * containerised command and reports whether the two answers differ under the\n * reserved {@link key}. The harness reads that key as a measured write, the\n * way it reads `invalidProbe` as a measured refusal.\n *\n * The same properties as the host walk, and the same stated limits:\n *\n * - **Identity, not content.** Size and mtime per file; a rewrite that\n *   restores both is invisible.\n * - **Pruning is the signal.** {@link defaultPrune} and\n *   {@link defaultIgnoreSuffixes} are the one list both measurements use, so\n *   a derived artifact the host walk skips is skipped here too.\n * - **A partial listing says so.** The listing stops at {@link maxPaths}, and\n *   a measurement that stopped there reports `complete: false`; `bash` then\n *   reports nothing rather than a guess.\n * - **Every tool it needs is POSIX or busybox.** `find -prune`, `stat -c`,\n *   `sort`, `head`, `cksum` and `grep -c` are in every Linux base image this\n *   has been run against, GNU and busybox alike. A container that lacks one\n *   answers with a non-zero exit, which is read as \"unmeasured\".\n *\n * @since 1.0.0\n */\n\nimport * as Prune from \"./internal/Prune.ts\"\n\n/**\n * The reserved output key a flow reports a measured write under.\n *\n * A wire contract with the harness rather than a shared type, exactly as\n * `Probe.key` is: `@smthrs/harness` reads this key off a `Schema.Json` result\n * and must not depend on the tool library to do it. `true` means the tree the\n * call targeted differed after the call from before it; `false` means it was\n * measured and held still; absent means it was not measured.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const key = \"mutated\"\n\n/**\n * Directory names never descended into.\n *\n * Every entry is a place a tool writes derived state while the run is working:\n * version-control internals, dependency trees, and the caches Python, Node,\n * Rust and their test runners keep beside the sources. A run that changes only\n * these has changed nothing it will be judged on.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const defaultPrune: ReadonlyArray<string> = [\n  ...Prune.repositoryDirectories,\n  // Build and environment directories a search still reads, since a project\n  // may keep sources under these names, but a measurement leaves out.\n  \"venv\",\n  \"target\"\n]\n\n/**\n * File and directory name suffixes left out of a measurement.\n *\n * Compiled output is the case that matters: several SWE-bench projects build\n * extensions in place, which drops `.so` files next to the `.py` files they\n * came from. Those move whenever the run executes its test suite, and\n * counting them would report every probe as an edit.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const defaultIgnoreSuffixes: ReadonlyArray<string> = [\n  \".pyc\",\n  \".pyo\",\n  \".pyd\",\n  \".so\",\n  \".o\",\n  \".a\",\n  \".dylib\",\n  \".class\",\n  \".egg-info\"\n]\n\n/**\n * The largest number of files one measurement covers.\n *\n * The same bound the host walk uses, for the same reason: a listing that\n * stopped here covers a prefix chosen by sort order, and a prefix holding\n * still says nothing about the files being edited outside it.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const maxPaths = 50_000\n\n/**\n * One measurement, as {@link parse} reads it off the script's output.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Measurement {\n  /** The checksum of the whole listing; equal for two measurements of an unchanged tree. */\n  readonly digest: string\n  /** How many files the listing covered. */\n  readonly paths: number\n  /** Whether the listing covered the whole tree rather than a bounded prefix. */\n  readonly complete: boolean\n}\n\n/** One name, single-quoted for a POSIX shell. Every name here is a constant without quotes in it. */\nconst quoted = (name: string): string => `'${name.replaceAll(\"'\", `'\\\\''`)}'`\n\n/**\n * The POSIX shell script that measures the current directory.\n *\n * Prints two lines: `cksum`'s `<crc> <bytes>` over the sorted listing, then\n * the number of listing lines. The listing is capped one past\n * {@link maxPaths} so the count alone says whether the bound was reached.\n * Errors from `find` and `stat` are discarded: a path that vanished mid-walk\n * is movement the next measurement reports, and a file the shell may not\n * stat is one it could not have measured either way.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const script = (options: {\n  readonly prune?: ReadonlyArray<string> | undefined\n  readonly ignoreSuffixes?: ReadonlyArray<string> | undefined\n} = {}): string => {\n  const prune = (options.prune ?? defaultPrune).map((name) => `-name ${quoted(name)}`).join(\" -o \")\n  const skipped = (options.ignoreSuffixes ?? defaultIgnoreSuffixes)\n    .map((suffix) => `! -name ${quoted(`*${suffix}`)}`)\n    .join(\" \")\n  return [\n    \"set -f\",\n    `L=$(find . -xdev \\\\( ${prune} \\\\) -prune -o -type f ${skipped} -exec stat -c '%s %Y %n' {} + 2>/dev/null | LC_ALL=C sort | head -n ${\n      maxPaths + 1\n    })`,\n    `printf '%s' \"$L\" | cksum`,\n    `printf '%s' \"$L\" | grep -c ''`\n  ].join(\"\\n\")\n}\n\n/**\n * Reads one measurement off the script's standard output.\n *\n * `undefined` for anything that is not two well-formed lines: the script did\n * not run, a tool it needs is missing, or the output was cut. An unmeasured\n * tree is reported as unmeasured, never as unchanged.\n *\n * @category conversions\n * @since 1.0.0\n */\nexport const parse = (stdout: string): Measurement | undefined => {\n  const lines = stdout.trim().split(\"\\n\").map((line) => line.trim())\n  if (lines.length !== 2) return undefined\n  const checksum = /^(\\d+) (\\d+)$/.exec(lines[0]!)\n  const count = /^(\\d+)$/.exec(lines[1]!)\n  if (checksum === null || count === null) return undefined\n  const paths = Number(count[1])\n  const bounded = paths > maxPaths\n  return {\n    digest: `${checksum[1]}:${checksum[2]}`,\n    paths: bounded ? maxPaths : paths,\n    complete: !bounded\n  }\n}\n\n/**\n * Whether two measurements say the tree moved, or nothing at all.\n *\n * `true` and `false` are answers; `undefined` is the honest reading whenever\n * either measurement is absent or bounded, because a prefix that held still\n * is not a tree that held still.\n *\n * @category conversions\n * @since 1.0.0\n */\nexport const moved = (\n  before: Measurement | undefined,\n  after: Measurement | undefined\n): boolean | undefined =>\n  before === undefined || after === undefined || !before.complete || !after.complete\n    ? undefined\n    : before.digest !== after.digest\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuCA,YAAuB;AAchB,MAAM,MAAM;AAaZ,MAAM,eAAsC;AAAA,EACjD,GAAG,MAAM;AAAA;AAAA;AAAA,EAGT;AAAA,EACA;AACF;AAaO,MAAM,wBAA+C;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAYO,MAAM,WAAW;AAkBxB,MAAM,SAAS,CAAC,SAAyB,IAAI,KAAK,WAAW,KAAK,OAAO,CAAC;AAenE,MAAM,SAAS,CAAC,UAGnB,CAAC,MAAc;AACjB,QAAM,SAAS,QAAQ,SAAS,cAAc,IAAI,CAAC,SAAS,SAAS,OAAO,IAAI,CAAC,EAAE,EAAE,KAAK,MAAM;AAChG,QAAM,WAAW,QAAQ,kBAAkB,uBACxC,IAAI,CAAC,WAAW,WAAW,OAAO,IAAI,MAAM,EAAE,CAAC,EAAE,EACjD,KAAK,GAAG;AACX,SAAO;AAAA,IACL;AAAA,IACA,wBAAwB,KAAK,0BAA0B,OAAO,wEAC5D,WAAW,CACb;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI;AACb;AAYO,MAAM,QAAQ,CAAC,WAA4C;AAChE,QAAM,QAAQ,OAAO,KAAK,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC;AACjE,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,QAAM,WAAW,gBAAgB,KAAK,MAAM,CAAC,CAAE;AAC/C,QAAM,QAAQ,UAAU,KAAK,MAAM,CAAC,CAAE;AACtC,MAAI,aAAa,QAAQ,UAAU,KAAM,QAAO;AAChD,QAAM,QAAQ,OAAO,MAAM,CAAC,CAAC;AAC7B,QAAM,UAAU,QAAQ;AACxB,SAAO;AAAA,IACL,QAAQ,GAAG,SAAS,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC;AAAA,IACrC,OAAO,UAAU,WAAW;AAAA,IAC5B,UAAU,CAAC;AAAA,EACb;AACF;AAYO,MAAM,QAAQ,CACnB,QACA,UAEA,WAAW,UAAa,UAAU,UAAa,CAAC,OAAO,YAAY,CAAC,MAAM,WACtE,SACA,OAAO,WAAW,MAAM;",
+  "names": []
+}

package/dist/cjs/UpdatePlan.d.ts

@@ -0,0 +1,152 @@
+/**
+ * update_plan flow declaration and portable handler.
+ *
+ * A Codex CLI clone of the `update_plan` tool: an optional explanation and a
+ * list of plan items, acknowledged with "Plan updated". Pure — no host
+ * access; the harness observes plan updates through the journal.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+/**
+ * Registry name for the update_plan flow. Matches the Codex CLI tool name.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "update_plan";
+/**
+ * Model-facing description of the update_plan flow. Matches the Codex CLI
+ * description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description: string;
+/**
+ * Status of one plan step, matching Codex.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const StepStatus: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+/**
+ * The plan itself: steps, at most one of them `in_progress`.
+ *
+ * The single-in-progress rule is the last line of the Codex description a
+ * model reads every frame, so it is enforced here rather than left as prose a
+ * decode ignores. A plan naming two running steps is a decode failure at the
+ * `plan` path, not a silent acknowledgement.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Plan: Schema.$Array<Schema.Struct<{
+    readonly step: Schema.String;
+    readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+}>>;
+/**
+ * Input schema for the update_plan flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly explanation: Schema.optional<Schema.String>;
+    readonly plan: Schema.$Array<Schema.Struct<{
+        readonly step: Schema.String;
+        readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+    }>>;
+}>;
+/**
+ * Decoded input accepted by the `update_plan` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the update_plan flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly output: Schema.String;
+}>;
+/**
+ * Decoded output returned by the `update_plan` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static effect envelope for the update_plan flow: no reads, no writes.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * The flow touches nothing, so every invocation declares what the static
+ * envelope declares.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the update_plan flow: none.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: ReadonlyArray<string>;
+/**
+ * Declaration-only update_plan flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "update_plan";
+    readonly description: string;
+    readonly input: Schema.Struct<{
+        readonly explanation: Schema.optional<Schema.String>;
+        readonly plan: Schema.$Array<Schema.Struct<{
+            readonly step: Schema.String;
+            readonly status: Schema.Literals<readonly ["pending", "in_progress", "completed"]>;
+        }>>;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly output: Schema.String;
+    }>;
+    readonly capabilities: readonly string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * Acknowledges a plan update with Codex's exact response text.
+ *
+ * The single-in-progress rule is checked again here. `Plan` refuses it at
+ * decode time, but a host that calls this handler directly never decodes, and
+ * an invariant enforced in only one of the two entrances is enforced in
+ * neither.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly plan: readonly {
+        readonly step: string;
+        readonly status: "pending" | "completed" | "in_progress";
+    }[];
+    readonly explanation?: string | undefined;
+}) => Effect.Effect<{
+    readonly output: string;
+}, StdError.StdError, never>;
+//# sourceMappingURL=UpdatePlan.d.ts.map

package/dist/cjs/UpdatePlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpdatePlan.d.ts","sourceRoot":"","sources":["../../src/UpdatePlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,gBAAgB,CAAA;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,QAE4B,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,mEAA2D,CAAA;AAWlF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI;;;GAU+B,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;EAGhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;EAEjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAAwE,CAAA;AAE5F;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAM,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;CAAsF,CAAA;AAEvG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG;;;;;;;;4BAad,CAAA"}