vouchington-tooling 0.44.0 → 0.46.0

package/dist/private-files/log-file.mjs

@@ -0,0 +1,53 @@
+import { closeSync, constants, fstatSync, openSync, readSync, writeSync } from 'node:fs';
+import { decodeUtf8 } from "./utf8.mjs";
+export function openLogFile(path, flags) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ELOOP' || error.code === 'EISDIR' || error.code === 'ENOTDIR'))
+            throw new Error('log file must be a regular file');
+        throw error;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        if (!status.isFile() || status.nlink !== 1)
+            throw new Error('log file must be a regular file');
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+export function readLogContent(descriptor, maximumBytes) {
+    if (fstatSync(descriptor).size > maximumBytes)
+        throw new Error('log file is too large');
+    const buffer = Buffer.alloc(maximumBytes + 1);
+    let length = 0;
+    while (length < buffer.length) {
+        const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+        if (bytes === 0)
+            break;
+        length += bytes;
+    }
+    /* v8 ignore next -- detects external growth after the descriptor size check. */
+    if (length > maximumBytes)
+        throw new Error('log file is too large');
+    return decodeUtf8(buffer.subarray(0, length));
+}
+export function writeAll(descriptor, value) {
+    const buffer = Buffer.from(value);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const written = writeSync(descriptor, buffer, offset, buffer.length - offset);
+        /* v8 ignore next -- a zero-byte synchronous file write is an external I/O failure. */
+        if (written === 0)
+            throw new Error('log file write made no progress');
+        offset += written;
+    }
+}

package/dist/{session-friction → private-files}/utf8.mjs

@@ -3,6 +3,6 @@ export function decodeUtf8(value) {
         return new TextDecoder('utf-8', { fatal: true }).decode(value);
     }
     catch {
-        throw new Error('session-friction log is not valid UTF-8');
+        throw new Error('log file is not valid UTF-8');
     }
 }

package/dist/retrospective-facts/exec.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 export const shell = (command, args) => new Promise((resolve) => {
-    const child = spawn(command, args);
+    const child = command === 'gh' ? spawn(command, args, { env: ghSpawnEnv() }) : spawn(command, args);
     let stdout = '';
     let stderr = '';
     child.stdout.setEncoding('utf8');

package/docs/mcp-server.md

@@ -82,17 +82,18 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
 as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
 
-| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                             | Returns                                                                                                                                          |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`       | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
-| `journal_entries`     | none                                                                                                                                                                                     | `sessionId` and `entries`, every entry oldest first                                                                                              |
-| `outbox_status`       | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
-| `outbox_flush`        | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
-| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                    | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
-| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                 | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
-| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown` and `policy.warnings`                                                      |
-| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                          | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
-| `session_archive`     | none                                                                                                                                                                                     | `sessionId`, `archived: true`                                                                                                                    |
+| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                                                                                                                                  | Returns                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`                                                                                                            | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
+| `journal_entries`     | none                                                                                                                                                                                                                                                                                          | `sessionId` and `entries`, every entry oldest first                                                                                              |
+| `outbox_status`       | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
+| `outbox_flush`        | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
+| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                                                                                                                         | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
+| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                                                                                                                      | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
+| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings`                                      |
+| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                                                                                                               | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
+| `snapshot_cleanup`    | `cleanupToken`                                                                                                                                                                                                                                                                                | `sessionId`, `cleaned: true`                                                                                                                     |
+| `session_archive`     | none                                                                                                                                                                                                                                                                                          | `sessionId`, `archived: true`                                                                                                                    |
 
 `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
 anything is written, so a missing required field writes nothing. It returns the verified read-back
@@ -146,6 +147,35 @@ outbox does not create the directory. `snapshot_export` never accepts a destinat
 `agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
 destructive tool; archived metadata is immutable, while entries stay appendable.
 
+### Snapshot cleanup
+
+`snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
+way to delete it through the server. It was chosen over cleanup inside `session_archive` because
+the exporting session and the archived sessions differ during distillation, and cleanup must run
+whether or not archiving happened. Call it as a finally step after processing, on success and on
+failure.
+
+- **No caller-chosen path.** The tool takes only `cleanupToken` (`path`, `directory`, and `receipt`
+  are unsupported arguments). The server records the export's file path itself, plus a partition
+  directory and its signed receipt when the client reports both, and cleans exactly that record.
+  When the client's export carried its own cleanup capability, the server keeps it (never
+  returning it) and cleans through the client's `cleanupSnapshotPartitions`, so the client's
+  ownership marker goes with the file; otherwise it uses the in-tree `cleanupSnapshotPartitions`.
+- **Server-minted, bound token.** `snapshot_export` replaces the client's `cleanupToken` with 32
+  random bytes the server generates, recorded with the caller's `sessionId` and resolved `worktree`.
+  The binding is checked before any filesystem call.
+- **Single use.** A successful cleanup spends the token; a repeat fails as unknown and deletes
+  nothing. The record is taken synchronously, so concurrent calls cannot both clean.
+- **Failure modes.** An unknown, forged (including a path used as a token), spent, other-session, or
+  other-worktree token fails with one message and deletes nothing; a mismatched caller does not spend
+  the owner's token. If the cleanup itself fails, the token stays valid and the error carries the
+  reason, including the retained tombstone path when a partition directory was half removed, so the
+  same call can retry. A file that is already gone counts as cleaned.
+- **Server restart.** Bindings are in memory only. After a restart every earlier token is unknown, so
+  the file is left for the operating system to reap from its temp directory; run the distill pass
+  again to export a fresh snapshot. The registry also remembers at most 256 exports and forgets the
+  oldest first.
+
 The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
 Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
 
@@ -168,7 +198,9 @@ instructions shows it to the agent.
 ## Retrospective tools and the policy contract
 
 `retrospective_check` reads the session through the same client as `journal_entries` and reports the
-entries whose envelope `type` is `retrospective`. A session that was never created (the blackboard
+entries whose envelope `type` is `retrospective`. A schema-versioned entry counts only when its
+envelope passes `validateFeedbackEnvelope`; a malformed one is not saved, while an unversioned legacy
+entry is still accepted. A session that was never created (the blackboard
 answers 404) reports `saved: false`.
 
 `retrospective_save` builds a `retrospective` envelope and writes it exactly as `journal_append`
@@ -189,7 +221,20 @@ are killed after 120 seconds. `compose.facts` takes `pr`, `branch`, `noPr`, or `
 worktree's. Facts run `git` and `gh` in the worktree as the server's user, honoring its
 repository configuration (which can select helpers that run code), so the worktree, including
 `.git/config`, must be as trusted as the policy module. `dryRun`
-runs every check and returns the document without writing.
+runs every check and returns the document without writing, plus a `previewToken`.
+
+`knownSensitiveValues` (each at least 4 characters) is also accepted beside `markdown`, and
+redacts the markdown, `category` and `feedbackCoverage` just as `compose.knownSensitiveValues`
+does; with `compose`, pass it inside `compose`. The `previewToken` is 32 random bytes (base64url),
+opaque, single use, and held only in server memory: a restart drops every token, and the registry
+keeps the 32 most recent. It is bound to the `sessionId`, `parentSessionId`, `mode`, the resolved worktree, the `sourceEventId`
+and the exact redacted content. Save it by calling `retrospective_save` again with the identity,
+the same `parentSessionId`, `mode`, `sourceEventId` and `previewToken`, and none of `markdown`, `compose`,
+`workOutcome`, `feedbackCoverage`, `repositories`, `category`, `knownSensitiveValues` or `dryRun`.
+The server stores exactly the previewed content (so a sensitive value never has to be sent
+again), mints a new timestamp, and does not run the policy again. An unknown, spent, restarted or
+mismatched token is one error and the dry run must be repeated; a mismatch does not spend the
+token, and neither does a failed write.
 
 The document must open with the front matter `composeRetrospective` writes: lines of
 `key: <JSON value>` between two `---` lines. Recognized keys are `date`, `issues`, `prs` (required),
@@ -229,7 +274,7 @@ whole process group is killed, so nothing it started outlives the call. The runn
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
 | `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }`                    | 30 s    |
 | `pullRequestDefaults`   | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create`                                                                                           | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s   |
-| `validatePullRequest`   | `title`, `body`, `base`, `head`, `mode`, and `pr` for an update                                                                                                             | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, the trusted `mode`, `noSourceIssue` when given, and `pr` when set                                                                          | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
 
 Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
 `policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
@@ -241,9 +286,45 @@ shape is an error, never a pass.
 retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
 launched inside a repository worktree (they run the checkout policy), and share this structured
 input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
-(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), `details` (string array),
-`base` (default `main`), `agent`, optional `model`, `mode` (`interactive` | `autonomous`) and
-`workspaceSetup`. `pr_update` also requires `pr`; `pr_validate` accepts an optional `pr`.
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), optional `noSourceIssue`
+(`{ reason }`, see below), `details` (string array), `base` (default `main`), optional `agent`, optional
+`model`, optional `mode` (`interactive` | `autonomous`) and `workspaceSetup`. `pr_update` also
+requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Trusted mode
+
+The mode the policy sees is derived by the server from its own launch environment, never from the
+caller. It fails closed: when any automation marker is set to something other than an empty
+string, `0` or `false` (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`,
+`JENKINS_URL`, `TF_BUILD`, `CODEBUILD_BUILD_ID`, `VOUCHINGTON_AUTOMATION`), the mode is
+`autonomous` whatever the caller passes. `CLAUDE_CODE_SESSION_ATTENDED` set to exactly `0` (Claude
+Code's marker for an unattended `claude -p` run, inherited by MCP servers) also means `autonomous`;
+a missing value or `1` never does. This list is a superset of the downstream check it replaces,
+which was exactly `GITHUB_ACTIONS === 'true' || CI === 'true'`. Otherwise the mode is `interactive`. The optional `mode`
+argument can only narrow `interactive` to `autonomous` (it never widens), so an autonomous run
+cannot unlock an interactive-only policy exception. The policy child receives no env markers, so it
+relies on this value.
+
+### Agent provenance
+
+The `Agent:` line is derived by the server, never taken from the caller. The agent is the harness
+that launched the server: `CODEX_THREAD_ID` (codex), `CLAUDECODE=1` or `CLAUDE_CODE_SESSION_ID`
+(claude), `CURSOR_AGENT` or `CURSOR_SESSION_ID` (cursor), `GROK_AGENT`, `GROK_HOOK_EVENT` or
+`GROK_SESSION_ID` (grok), in that order; failing those, the MCP client's `initialize`
+`clientInfo.name` when it contains one of those names. The server has no source for the model.
+`agent` is optional: a value naming the derived agent is ignored, any other value is rendered as
+`(caller-claimed agent: <value>)`, and `model` as `(caller-claimed model: <value>)`. When no agent
+is derivable the line says `unknown`. Making `agent` optional is compatible with existing callers,
+which may keep sending it.
+
+### Pull requests with no source issue
+
+Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`; a non-empty
+`relatedIssues` beside it is rejected. The Related issues section then holds the generic statement
+`- No source issue — <reason>` instead of `- None`. A policy may replace the statement by
+exporting `renderNoSourceIssue({ reason })`, returning a non-empty string (30 s). The field also
+reaches `validatePullRequest` (with the trusted `mode`, so the policy can apply an interactive-only
+rule) and `pullRequestDefaults`.
 
 ### Rendering
 
@@ -258,35 +339,40 @@ input: `title` (single line, at most 256 characters), `summary`, `impact`, `rela
 
 ## Related issues
 
-- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty;
+                             "- No source issue — <reason>" for noSourceIssue)
 
 ## Details
 
 <details joined by blank lines>
 
 Workspace setup: <workspaceSetup>
-Agent: <agent>[ (<model>)] session <sessionId>
+Agent: <derived agent | unknown>[ (caller-claimed ...)] session <sessionId>
 Device: <os user>@<lowercased hostname>
 Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
 ```
 
-The head branch is the worktree's current branch; a detached HEAD, or a head equal to `base`, is
-rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
+The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
+request's head, which may equal `base` for a fork); otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
 so a consumer policy may reject any `base` other than the default branch; create stacked layers
 with the repository's stack tooling instead.
 
 ### Tools
 
 - `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
-  base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
-  body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
+  base, head, mode, noSourceIssue?, pr? })` export and returns `{ body, errors, warnings }`. With
+  `pr`, the live body is read (never written) so its Shepherd Journal is preserved as in
+  `pr_update`. The liveness checks of `pr_update` do not apply: any state (merged or closed
+  included) and any head are accepted, and the policy sees the pull request's own head and base.
 - `pr_create` (additive): renders and validates (errors block), then calls the policy
-  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  `pullRequestDefaults({ title, base, relatedIssues, noSourceIssue? })` export for optional `labels`, `milestone`
   and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
   (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
   `--project`. Returns `{ number, url, warnings }`.
-- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,baseRefName,state`,
-  rejects a pull request that is not `OPEN` or whose head is not the worktree branch, and validates
+- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,headRefOid,baseRefName,state`,
+  rejects a pull request that is not `OPEN` or whose head is neither the worktree branch nor the
+  worktree `HEAD` commit (an alias branch at the live head SHA is accepted and the live head name is
+  used), and validates
   against the live base (an explicit `base` must equal it). It renders, appends the live Shepherd
   Journal (a `<details><summary>Shepherd Journal</summary>` block, or a legacy `## Shepherd Journal`
   section to the next H2 or the end; examples in fenced code blocks are ignored), validates with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -71,11 +71,6 @@
       "default": "./dist/agent-blackboard/index.mjs"
     },
     "./mcp-server/bin": "./bin/vouchington-mcp.mjs",
-    "./session-friction": {
-      "types": "./dist/session-friction/index.d.mts",
-      "import": "./dist/session-friction/index.mjs",
-      "default": "./dist/session-friction/index.mjs"
-    },
     "./sql-ast": {
       "types": "./dist/sql-ast/index.d.mts",
       "import": "./dist/sql-ast/index.mjs",
@@ -391,13 +386,13 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@ast-grep/cli": "0.45.3",
+    "@ast-grep/cli": "0.50.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",
     "no-mistakes": "0.83.0",
-    "smol-toml": "1.9.0",
+    "smol-toml": "1.9.1",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {

package/skills/retrospective/SKILL.md

@@ -15,7 +15,9 @@ local `AGENTS.md`, and journal guidance first.
 1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
    material new observation before filing a follow-up issue. Preserve entry-level repository tags.
 2. Generate routine repository and transcript facts with the approved composer: pass `compose` to
-   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Keep exact factual
+   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Save the preview by passing its
+   `previewToken` to `retrospective_save` (no markdown); put sensitive values only in
+   `compose.knownSensitiveValues`, or `knownSensitiveValues` for a markdown save. Keep exact factual
    section markers generated, preserve unavailable counts, and never replace missing evidence with
    invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
 3. Record work outcome, feedback coverage, and delivery independently. Success, failure,

package/skills/retrospective-distill/SKILL.md

@@ -126,6 +126,11 @@ difference is a conflicting payload and stays quarantined.
   sessions into retrospective and stale (checkpoint-only, journal-only, zero-entry child, and
   zero-entry root).
 
+Cleanup, as a finally step: whether processing succeeded or failed, call `snapshot_cleanup` with
+the `cleanupToken` from `snapshot_export`, with the same `sessionId` and `worktree`, once the
+snapshot is no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
+retry the same call.
+
 Use source records only for local verification and leave them in the repository's approved journal
 or retention system. Public issue bodies contain only the minimum bounded facts or redacted
 summaries needed to establish the problem, proposed work, relevant areas, and validation. Never

package/dist/session-friction/ci-failures.d.mts

@@ -1,13 +0,0 @@
-import type { FrictionLogReadResult, JournalEntry } from './types.mts';
-import { type AuditRedactor } from './text.mts';
-export declare function isConformingCiFailureBlock(markdown: string): boolean;
-export declare function getConformingGroups(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
-export declare function incompleteCiSection(markdownBlocks: string[]): string;
-export declare function buildCiFailuresSection(sessionId: string, journal: {
-    status: 'ok';
-    markdownBlocks: string[];
-    truncated: boolean;
-} | {
-    status: 'unreachable';
-    diagnostic: string;
-}, frictionStatus: FrictionLogReadResult['status'] | 'journal-only'): string;

package/dist/session-friction/classify.d.mts

@@ -1,2 +0,0 @@
-import type { FrictionEvent, FrictionObservation } from './types.mts';
-export declare function classifyFrictionObservation(observation: FrictionObservation): Omit<FrictionEvent, 'timestamp'> | null;

package/dist/session-friction/classify.mjs

@@ -1,98 +0,0 @@
-import { normalizeCommandPrefix } from "./normalize.mjs";
-import { boundedText, isWellFormedUnicode, normalizeAuditText } from "./text.mjs";
-const FAILURE_TOKENS = [
-    ['Operation not permitted', /Operation not permitted/i],
-    ['E2BIG', /\bE2BIG\b/i],
-    ['EPERM', /\bEPERM\b/i],
-];
-const CONNECTION_REFUSED = /\bECONNREFUSED\b/i;
-const URL_USERINFO = /([a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/?#@]*@/gi;
-const STDERR_INSPECTION_MAX_LENGTH = 100_000;
-const COMMAND_INSPECTION_MAX_LENGTH = 10_000;
-const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]?\\d)';
-const LOOPBACK_ADDRESSES = [
-    new RegExp(String.raw `(?<![0-9a-z_.:-])(?:127\.${IPV4_OCTET}(?:\.${IPV4_OCTET}){2}|localhost)(?![0-9a-z_.-])`, 'i'),
-    /(?<![0-9a-z_.-])\[(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?\](?![0-9a-z_.-])/i,
-    /(?<![0-9a-z_.:\x5b\x5d-])(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?(?::\d{1,5})?(?![0-9a-z_.:\x5b\x5d-])/i,
-];
-const DETAIL_MAX_LENGTH = 1_000;
-function boundedTail(value, maximum) {
-    let start = Math.max(0, value.length - maximum);
-    const first = value.charCodeAt(start);
-    const previous = value.charCodeAt(start - 1);
-    if (first >= 0xdc00 && first <= 0xdfff && previous >= 0xd800 && previous <= 0xdbff)
-        start++;
-    return value.slice(start);
-}
-function boundedStderr(value) {
-    if (value.length <= STDERR_INSPECTION_MAX_LENGTH)
-        return value;
-    const headLength = Math.floor((STDERR_INSPECTION_MAX_LENGTH - 1) / 2);
-    const head = boundedText(value, headLength);
-    const tail = boundedTail(value, STDERR_INSPECTION_MAX_LENGTH - 1 - head.length);
-    return `${head}\n${tail}`;
-}
-function withoutUrlUserinfo(line) {
-    return line.includes('://') && line.includes('@') ? line.replace(URL_USERINFO, '$1') : line;
-}
-export function classifyFrictionObservation(observation) {
-    if (!observation || typeof observation !== 'object')
-        return null;
-    if (typeof observation.command !== 'string')
-        return null;
-    const command = boundedText(observation.command, COMMAND_INSPECTION_MAX_LENGTH);
-    if (!isWellFormedUnicode(command) || normalizeAuditText(command) === '')
-        return null;
-    const commandPrefix = normalizeCommandPrefix(command, observation.commandWrappers);
-    if (commandPrefix === '' || !isWellFormedUnicode(commandPrefix))
-        return null;
-    if (observation.type === 'permission-request') {
-        return {
-            kind: 'sandbox-escalation',
-            commandPrefix,
-            detail: 'permission-request',
-            outcome: 'requested',
-        };
-    }
-    if (observation.type !== 'tool-result')
-        return null;
-    if (observation.escalationDetail !== undefined &&
-        typeof observation.escalationDetail !== 'string')
-        return null;
-    const escalationDetail = normalizeAuditText(boundedText(observation.escalationDetail ?? '', DETAIL_MAX_LENGTH));
-    if (!isWellFormedUnicode(escalationDetail))
-        return null;
-    if (observation.permissionOutcome !== undefined &&
-        !['approved', 'denied'].includes(observation.permissionOutcome))
-        return null;
-    const permission = escalationDetail || observation.permissionOutcome
-        ? {
-            kind: 'sandbox-escalation',
-            commandPrefix,
-            detail: escalationDetail || `permission-${observation.permissionOutcome}`,
-            outcome: observation.permissionOutcome ?? 'unknown',
-        }
-        : null;
-    const rawStderr = observation.structuredStderr;
-    if (rawStderr !== undefined && (typeof rawStderr !== 'string' || !isWellFormedUnicode(rawStderr)))
-        return null;
-    const stderr = rawStderr ? boundedStderr(rawStderr) : rawStderr;
-    if (stderr === undefined)
-        return permission;
-    const token = FAILURE_TOKENS.find(([, pattern]) => pattern.test(stderr))?.[0];
-    if (token) {
-        const failure = { kind: 'sandbox-failure', detail: `stderr matched "${token}"` };
-        return permission ? { ...permission, failure } : { ...failure, commandPrefix };
-    }
-    if (stderr.split(/\r\n|[\r\n]/).some((rawLine) => {
-        const line = withoutUrlUserinfo(rawLine);
-        return (CONNECTION_REFUSED.test(line) && LOOPBACK_ADDRESSES.some((pattern) => pattern.test(line)));
-    })) {
-        const failure = {
-            kind: 'ambiguous-failure',
-            detail: 'localhost connection refused; sandbox cause unverified',
-        };
-        return permission ? { ...permission, failure } : { ...failure, commandPrefix };
-    }
-    return permission;
-}

package/dist/session-friction/command-segments.d.mts

@@ -1,3 +0,0 @@
-export declare const REDACTED_TOKEN = "[REDACTED]";
-export declare function splitCommand(command: string): string[][];
-export declare function stripAssignments(tokens: string[]): string[];

package/dist/session-friction/command-segments.mjs

@@ -1,94 +0,0 @@
-export const REDACTED_TOKEN = '[REDACTED]';
-const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
-const ENV_OPTIONS_WITH_ARGS = new Set(['-C', '--chdir', '-S', '--split-string', '-u', '--unset']);
-const ENV_OPTIONS_WITHOUT_ARGS = new Set([
-    '-i',
-    '--ignore-environment',
-    '-0',
-    '--null',
-    '-v',
-    '--debug',
-]);
-export function splitCommand(command) {
-    const result = [];
-    let segment = [];
-    let word = '';
-    let quote;
-    let escaped = false;
-    const flushWord = () => {
-        if (word)
-            segment.push(word);
-        word = '';
-    };
-    const flushSegment = () => {
-        flushWord();
-        if (segment.length)
-            result.push(segment);
-        segment = [];
-    };
-    for (const char of command) {
-        if (escaped) {
-            word += char;
-            escaped = false;
-        }
-        else if (char === '\\' && quote !== "'") {
-            escaped = true;
-        }
-        else if (quote) {
-            if (char === quote)
-                quote = undefined;
-            else
-                word += char;
-        }
-        else if (char === '"' || char === "'")
-            quote = char;
-        else if (';&|<>\n\r'.includes(char))
-            flushSegment();
-        else if (/\s/.test(char))
-            flushWord();
-        else
-            word += char;
-    }
-    if (escaped)
-        word += '\\';
-    flushSegment();
-    return result;
-}
-export function stripAssignments(tokens) {
-    let index = 0;
-    while (index < tokens.length && ENV_ASSIGNMENT.test(tokens[index]))
-        index++;
-    const wrapper = tokens[index];
-    // Assignments without an executable are represented by a safe sentinel.
-    if (wrapper !== 'env' && !wrapper?.endsWith('/env'))
-        return index < tokens.length ? tokens.slice(index) : index ? [REDACTED_TOKEN] : tokens;
-    index++;
-    while (index < tokens.length) {
-        const option = tokens[index];
-        if (option === '--') {
-            index++;
-            break;
-        }
-        const optionName = option.split('=', 1)[0];
-        const splitStringOption = optionName === '-S' || (optionName.length >= 5 && '--split-string'.startsWith(optionName));
-        if (splitStringOption)
-            return [REDACTED_TOKEN];
-        const abbreviatedArgument = optionName.length >= 5 && '--chdir'.startsWith(optionName);
-        if (ENV_OPTIONS_WITH_ARGS.has(optionName) || abbreviatedArgument) {
-            index += option.includes('=') ? 1 : 2;
-            continue;
-        }
-        if (ENV_OPTIONS_WITHOUT_ARGS.has(option)) {
-            index++;
-            continue;
-        }
-        if (option.startsWith('-'))
-            return [REDACTED_TOKEN];
-        break;
-    }
-    while (index < tokens.length && ENV_ASSIGNMENT.test(tokens[index]))
-        index++;
-    if (index < tokens.length)
-        return tokens.slice(index);
-    return tokens.some((token) => ENV_ASSIGNMENT.test(token)) ? [REDACTED_TOKEN] : [];
-}

package/dist/session-friction/coverage-ledger.d.mts

@@ -1,10 +0,0 @@
-export type CoverageLedger = {
-    schemaVersion: 1;
-    retainedEvents: number;
-    logBytes: number;
-    droppedCount: number;
-};
-/** Caller holds the event log lock; incomplete atomic updates must never imply complete capture. */
-export declare function readCoverageLedger(path: string): CoverageLedger | undefined;
-/** The fixed-size atomic sidecar keeps saturation work independent of the accumulated drop count. */
-export declare function writeCoverageLedger(path: string, ledger: CoverageLedger): void;