@basein/runner 0.2.12 → 0.3.1

package/dist/control/paths.d.ts

@@ -27,6 +27,25 @@ export declare function configPath(): string;
 export declare function logsDir(): string;
 /** The log file of the background recorder for `cwd`. */
 export declare function daemonLogPath(cwd: string): string;
+/**
+ * The log of a recorder that no longer serves the port `cwd`'s hooks post to
+ * (a reinstall moved them) but still serves the windows opened before that.
+ * Its own file, so the project's log has one writer and one rotation.
+ */
+export declare function supersededLogPath(cwd: string, port: number): string;
+/**
+ * The record of such a superseded recorder, one per process, so `bir status`,
+ * `bir down` and `bir uninstall` can find and stop it: the project's discovery
+ * file names only the recorder its hooks post to now.
+ */
+export declare function supersededPath(cwd: string, pid: number): string;
+/**
+ * Written when a recorder of `cwd` is stopped on purpose (`bir down`),
+ * removed when one is started again (a session start, `bir up`, `bir setup`).
+ * While it is there, a bound proxy that finds the recorder gone does not bring
+ * it back (`bir-hooks revive`).
+ */
+export declare function downMarkerPath(cwd: string): string;
 /** Create a directory with restrictive permissions. Idempotent, never throws. */
 export declare function ensureDir(dir: string, mode?: number): void;
 /**
@@ -43,4 +62,11 @@ export declare function normalizePath(p: string): string;
 export declare function controlKey(cwd: string): string;
 /** Absolute path of the discovery file for `cwd`. */
 export declare function discoveryPath(cwd: string): string;
+/**
+ * Where a background recorder that could not take this project's port says
+ * why — who holds it, or that the system reserved it — so `bir doctor` and the
+ * next SessionStart can name the problem instead of a hidden log line. Removed
+ * by the first recorder that binds the port again.
+ */
+export declare function portProblemPath(cwd: string): string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/control/paths.js

@@ -43,6 +43,31 @@ export function logsDir() {
 export function daemonLogPath(cwd) {
     return join(logsDir(), `${controlKey(cwd)}.log`);
 }
+/**
+ * The log of a recorder that no longer serves the port `cwd`'s hooks post to
+ * (a reinstall moved them) but still serves the windows opened before that.
+ * Its own file, so the project's log has one writer and one rotation.
+ */
+export function supersededLogPath(cwd, port) {
+    return join(logsDir(), `${controlKey(cwd)}.superseded-${port}.log`);
+}
+/**
+ * The record of such a superseded recorder, one per process, so `bir status`,
+ * `bir down` and `bir uninstall` can find and stop it: the project's discovery
+ * file names only the recorder its hooks post to now.
+ */
+export function supersededPath(cwd, pid) {
+    return join(controlDir(), `${controlKey(cwd)}.superseded.${pid}.json`);
+}
+/**
+ * Written when a recorder of `cwd` is stopped on purpose (`bir down`),
+ * removed when one is started again (a session start, `bir up`, `bir setup`).
+ * While it is there, a bound proxy that finds the recorder gone does not bring
+ * it back (`bir-hooks revive`).
+ */
+export function downMarkerPath(cwd) {
+    return join(controlDir(), `${controlKey(cwd)}.down`);
+}
 /** Create a directory with restrictive permissions. Idempotent, never throws. */
 export function ensureDir(dir, mode = 0o700) {
     try {
@@ -73,4 +98,13 @@ export function controlKey(cwd) {
 export function discoveryPath(cwd) {
     return join(controlDir(), `${controlKey(cwd)}.json`);
 }
+/**
+ * Where a background recorder that could not take this project's port says
+ * why — who holds it, or that the system reserved it — so `bir doctor` and the
+ * next SessionStart can name the problem instead of a hidden log line. Removed
+ * by the first recorder that binds the port again.
+ */
+export function portProblemPath(cwd) {
+    return join(controlDir(), `${controlKey(cwd)}.port.json`);
+}
 //# sourceMappingURL=paths.js.map

package/dist/control/pin-guard.d.ts

@@ -0,0 +1,83 @@
+/**
+ * pin-guard — whether a live call is plausibly the step a steering plan
+ * expects, before the control server rewrites it to the step's input.
+ *
+ * WHY THIS EXISTS. A steer plan pins "the next call to the expected tool", and
+ * the pin replaces the model's arguments with the step's and answers `allow`.
+ * Matching on the tool name alone meant that a model checking its work with
+ * `Bash ls` while a `Bash git push --force` step was due had Claude Code show
+ * `ls` and run the push, unasked. A tool name says which *kind* of call this
+ * is; it says nothing about whether the call is the step.
+ *
+ * The rule is deliberately conservative, because the two mistakes are not the
+ * same size. Not pinning a call that was the step costs a replay: the call
+ * runs as the model wrote it, and the plan stays armed for the call that is
+ * the step (the control server retires it, running nothing, if the model moves
+ * on to another tool instead). Pinning one that was not the step runs
+ * something the user never saw.
+ *
+ *   - `Bash` / `PowerShell`: the same command, or the same *commands*: as
+ *     many of them, chained the same way (`&&`, `||`, `;`, `|`, `&`, a new
+ *     line), each with the same head (the program, plus its subcommand when
+ *     it has one: `git push`, `npm test`; plus what it runs when it only runs
+ *     something else: `npm run lint`, `python deploy.py`). Comparing only the
+ *     first command's head pinned a model's `git status` to a step's `git
+ *     status && git push --force`. A step that runs a command substitution
+ *     (`$(…)`, backticks) is pinned only to an exact copy.
+ *   - Tools that write a file: the same file.
+ *   - MCP tools whose input is run — a query, a statement, a shell command
+ *     (replay/safety.ts `sinkOf`): every statement the step runs, supplied by
+ *     the model with the same verb (`SELECT` for `SELECT`, never for
+ *     `DELETE`), or no arguments at all. One shared key such as `sql` said
+ *     nothing about what the call does. An empty statement argument of the
+ *     step (`input: ""` beside the query) runs nothing and need not be
+ *     supplied — but a call that runs something there is not the step.
+ *   - Everything else: at least one argument in common, and no argument that
+ *     names *where* the call acts (a path, a URL) pointing somewhere else. A
+ *     call with no arguments at all is the model deferring to the directive
+ *     ("the system supplies the exact arguments") and is pinned.
+ *
+ * Read-only file tools are not held to the same file: pinning a `Read` of the
+ * wrong path to the step's path is exactly what the directive asks for, and it
+ * changes nothing on disk.
+ */
+export interface PinVerdict {
+    ok: boolean;
+    /** Why not, for the audit line. */
+    why?: string;
+}
+/**
+ * The part of a command that says what it does: the program and, when the
+ * next word reads like a subcommand, that too — `git push`, `npm test`,
+ * `docker compose`. Leading environment assignments and a leading `cd <dir> &&`
+ * are skipped; a path, a flag or a file name is not a subcommand.
+ *
+ * A program that only runs something else is named with what it runs —
+ * `npm run lint` (never just `npm run`, which would pin a lint to a deploy),
+ * `npx eslint`, `python deploy.py`, `python -m pytest`, `uv run pytest` —
+ * and a shell's inline command is that command: `bash -c "git push"` is
+ * `git push`.
+ */
+export declare function commandHead(command: string, depth?: number): string;
+/**
+ * A command line split into the commands it chains, at the separators that
+ * are not quoted or escaped: `&&`, `||`, `;`, `|` (and `|&`), a background
+ * `&`, a new line. A redirection's `&` (`2>&1`, `&>file`, `>&2`) is not one.
+ * `escape` is the shell's own escape character: a backslash in a POSIX shell,
+ * a backtick in PowerShell (where `C:\;` ends a command), a caret in cmd.
+ * Good enough to count and name the commands; not a shell parser.
+ */
+export declare function commandSegments(command: string, escape?: string): string[];
+/**
+ * What a command line does, command by command: the {@link commandHead} of
+ * each chained command, a shell's inline command expanded into its own, and a
+ * leading `cd <dir>` (which only says where) left out. Two command lines run
+ * the same things when these are equal.
+ */
+export declare function commandShape(command: string, depth?: number, escape?: string): string[];
+/**
+ * Whether the model's call `modelArgs` to `toolName` may be pinned to the
+ * step's `pinnedArgs`. See the file comment for the rule.
+ */
+export declare function pinCompatible(toolName: string, modelArgs: unknown, pinnedArgs: unknown): PinVerdict;
+//# sourceMappingURL=pin-guard.d.ts.map