dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/pstack/skills/statechart/scripts/statechart.test.mjs

@@ -0,0 +1,198 @@
+import { key, show } from "./ir.mjs";
+import { plainText } from "./backends/plain-text.mjs";
+import { compile } from "./pipeline.mjs";
+import { readConfig } from "./frontends/config.mjs";
+import { parseValue } from "./frontends/value.mjs";
+import { readMessages } from "./frontends/messages.mjs";
+import { readChecks } from "./frontends/spec.mjs";
+import { checkView, json } from "./frontends/view.mjs";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import { inspect } from "node:util";
+import assert from "node:assert/strict";
+// runtime/skills/statechart/scripts/statechart.test.ts
+const invariant = {
+	kind: "invariant",
+	name: "Inv"
+};
+function graphWithBreak() {
+	return {
+		states: /* @__PURE__ */ new Map([["s0", {
+			vars: { x: 0 },
+			start: true,
+			breaks: []
+		}], ["s1", {
+			vars: { x: 1 },
+			start: false,
+			breaks: [invariant]
+		}]]),
+		steps: [{
+			from: "s0",
+			to: "s1",
+			action: "Next"
+		}]
+	};
+}
+function resultWithBreak() {
+	return {
+		spec: {
+			module: "Test",
+			folder: "/tmp",
+			variables: ["x"],
+			invariants: ["Inv"],
+			properties: [],
+			deadlock: false,
+			written: []
+		},
+		graph: graphWithBreak(),
+		paths: void 0,
+		rules: [{
+			rule: invariant,
+			outcome: "broken",
+			messages: ["Inv is violated"]
+		}],
+		properties: [],
+		exit: 1,
+		stop: void 0,
+		drawing: void 0,
+		states: {
+			distinct: 2,
+			initial: 1,
+			complete: true,
+			cut: false
+		},
+		messages: ["TLC finished"]
+	};
+}
+test("reads the TLA+ value grammar the skill documents", () => {
+	assert.deepEqual(json(parseValue("<<1, \"a\", <<>>>>")), {
+		1: 1,
+		2: "a",
+		3: {}
+	});
+	assert.deepEqual(json(parseValue("{r1, -2}")), ["r1", -2]);
+	assert.deepEqual(json(parseValue("-1..2")), [
+		-1,
+		0,
+		1,
+		2
+	]);
+	assert.deepEqual(json(parseValue("[ok |-> TRUE, msg |-> \"say \\\"hi\\\"\"]")), {
+		ok: true,
+		msg: "say \"hi\""
+	});
+	assert.throws(() => parseValue("1.."), /cannot read TLA\+ value/);
+});
+test("prints each value in TLA+ and compares by TLA+ equality", () => {
+	assert.equal(show(parseValue("<<0>>")), "<<0>>");
+	assert.equal(show(parseValue("[a |-> 1]")), "[a |-> 1]");
+	assert.equal(key(parseValue("1..3")), key(parseValue("{3, 1, 2, 2}")));
+	assert.notEqual(key(parseValue("\"A\"")), key(parseValue("A")));
+});
+test("reads a TLC config into the checks the report names", () => {
+	const config = readConfig({
+		file: "Min.cfg",
+		text: "INIT Init\nNEXT Next\nINVARIANT Inv\nPROPERTY Live\n"
+	});
+	assert.equal(config.init, "Init");
+	assert.equal(config.next, "Next");
+	assert.deepEqual(config.invariants, ["Inv"]);
+	assert.deepEqual(config.properties, ["Live"]);
+	const checks = readChecks({
+		configFile: "Min.cfg",
+		config
+	});
+	assert.equal(checks.deadlock, true);
+});
+test("prints TLC's -tool messages as plain text", () => {
+	const text = [
+		"@!@!@STARTMSG 2262:0 @!@!@",
+		"TLC2 Version 2.19",
+		"@!@!@ENDMSG 2262 @!@!@"
+	].join("\n");
+	assert.equal([...plainText(readMessages(text))].join(""), "TLC2 Version 2.19\n");
+});
+test("compiles a broken rule into report.md, chart.mmd, and tlc.out", () => {
+	const compiled = compile(resultWithBreak(), checkView({}, inspect));
+	assert.equal(compiled.exit, 1);
+	const report = compiled.report;
+	assert.match(report, /Inv/);
+	assert.match(report, /Next/);
+	const chart = [...compiled.files.get("chart.mmd") ?? []].join("");
+	assert.match(chart, /stateDiagram/);
+	assert.match(chart, /Next/);
+	assert.ok(compiled.files.has("report.md"));
+	assert.ok(compiled.files.has("tlc.out"));
+});
+test("the CLI rejects a missing spec with usage and exit 2", () => {
+	const here = import.meta.dirname;
+	const entry = join(here, import.meta.url.endsWith(".ts") ? "statechart.ts" : "statechart.mjs");
+	const result = spawnSync(process.execPath, [entry], { encoding: "utf8" });
+	assert.equal(result.status, 2);
+	assert.match(result.stderr, /Give one SPEC\.tla\./);
+	assert.match(result.stderr, /Usage: statechart SPEC\.tla/);
+});
+test("the CLI runs the worker against TLC and writes the report, chart, and tlc.out", () => {
+	const root = mkdtempSync(join(tmpdir(), "statechart-worker-"));
+	try {
+		const caseDir = join(root, "case");
+		mkdirSync(caseDir);
+		writeFileSync(join(caseDir, "Smoke.tla"), "---- MODULE Smoke ----\n====\n");
+		writeFileSync(join(caseDir, "Smoke.cfg"), "INIT Init\nNEXT Next\n");
+		const fakeJava = join(root, "fake-java.mjs");
+		writeFileSync(fakeJava, String.raw`#!/usr/bin/env node
+import fs from "node:fs";
+const args = process.argv.slice(2);
+if (args.includes("tla2sany.xml.XMLExporter")) {
+  process.stdout.write('<modules><context><entry><UID>1</UID><OpDeclNode><uniquename>x</uniquename><kind>3</kind></OpDeclNode></entry><entry><UID>2</UID><ModuleNode><uniquename>Smoke</uniquename><OpDeclNodeRef><UID>1</UID></OpDeclNodeRef></ModuleNode></entry></context><RootModule>Smoke</RootModule></modules>');
+  process.exit(0);
+}
+const dump = args.indexOf("-dump");
+if (dump !== -1) {
+  fs.writeFileSync(args[dump + 2] + ".dot", [
+    "strict digraph DiskGraph {",
+    '1 [label="/\\\\ x = 0",style = filled]',
+    '2 [label="/\\\\ x = 1"]',
+    '1 -> 2 [label="Next"];',
+    "}",
+  ].join("\n"));
+}
+process.stdout.write("@!@!@STARTMSG 2199:0 @!@!@\n2 distinct states found.\n@!@!@ENDMSG 2199 @!@!@\n");
+process.exit(0);
+`);
+		chmodSync(fakeJava, 493);
+		const here = import.meta.dirname;
+		const entry = join(here, import.meta.url.endsWith(".ts") ? "statechart.ts" : "statechart.mjs");
+		const out = join(root, "out");
+		const result = spawnSync(process.execPath, [
+			entry,
+			join(caseDir, "Smoke.tla"),
+			"--out",
+			out
+		], {
+			encoding: "utf8",
+			env: {
+				...process.env,
+				JAVA: fakeJava,
+				TLA2TOOLS: "tla2tools.jar"
+			}
+		});
+		assert.equal(result.status, 0, result.stderr);
+		assert.deepEqual(readdirSync(out).sort(), [
+			"chart.mmd",
+			"report.md",
+			"tlc.out"
+		]);
+		assert.match(readFileSync(join(out, "report.md"), "utf8"), /# Smoke[\s\S]*NoDeadlock/);
+		assert.match(readFileSync(join(out, "chart.mmd"), "utf8"), /stateDiagram/);
+	} finally {
+		rmSync(root, {
+			recursive: true,
+			force: true
+		});
+	}
+});
+export {};

package/dist/pstack/skills/statechart/scripts/worker.mjs

@@ -0,0 +1,31 @@
+import { compile } from "./pipeline.mjs";
+import { check, messageOf } from "./run.mjs";
+import { checkView } from "./frontends/view.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { inspect } from "node:util";
+import { pathToFileURL } from "node:url";
+import { Buffer } from "node:buffer";
+// runtime/skills/statechart/scripts/worker.ts
+const [stage, specFile, configFile, viewFile] = process.argv.slice(2);
+try {
+	const view = checkView(viewFile ? await import(pathToFileURL(path.resolve(viewFile)).href) : {}, inspect);
+	const { files, exit } = compile(await check(specFile, configFile), view);
+	const draft = path.join(stage, "draft");
+	fs.mkdirSync(draft);
+	for (const [name, parts] of files) {
+		const fd = fs.openSync(path.join(draft, name), "wx");
+		try {
+			for (const part of parts) fs.writeSync(fd, typeof part === "string" ? Buffer.from(part) : part);
+			fs.writeSync(fd, "\n");
+		} finally {
+			fs.closeSync(fd);
+		}
+	}
+	fs.renameSync(draft, path.join(stage, "done"));
+	process.exit(exit);
+} catch (error) {
+	console.error(messageOf(error));
+	process.exit(2);
+}
+export {};

package/dist/pstack/skills/swarm/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: swarm
+description: "Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration."
+disable-model-invocation: true
+---
+
+# Swarm
+
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
+
+## Start
+
+Open a todolist with one entry per phase before launching anything.
+
+1. Frame
+2. Fan out
+3. Aggregate
+4. Report
+
+## Phase A: Frame
+
+1. State the done predicate and the artifact or report the swarm must return.
+2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
+3. Pick the worker model from the `swarm workers` line in `~/.cursor/rules/pstack-models.mdc`. If the rule or that line is missing, use `grok-4.7-xhigh-fast`. For `auto` or `inherit-parent`, omit `model` so the workers run on the parent model. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message. For a model race, name each arm's model up front. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+4. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
+
+## Phase B: Fan out
+
+Spawn all N workers in one message with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true`, and the step 3 model, left unset for `auto` or `inherit-parent`. Use `environment: "local"` only when the worker needs access to something on the user's computer.
+
+When a worker must start from a non-default pushed branch, pass `cloud_base_branch`.
+
+Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
+
+If a worker drops out, proceed with N-1 and note it.
+
+## Phase C: Aggregate
+
+Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
+
+## Phase D: Report
+
+Return one consolidated in-chat report with a result table, issue one-liners, gaps or dropouts, and the race rule when used.

package/{assets → dist/pstack}/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.
+description: "Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested."
 disable-model-invocation: true
 ---
 

package/{assets → dist/pstack}/skills/teach/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: teach
-description: Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'.
+description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
 disable-model-invocation: true
 ---
 
 # Teach
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
 **You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
 

package/{assets → dist/pstack}/skills/technical-writing/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Technical writing
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
 Write so a tired engineer understands on the first read. Apply all four layers.
 

package/{assets → dist/pstack}/skills/typescript-best-practices/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: typescript-best-practices
 description: TypeScript best practices. Use when reading or editing any .ts or .tsx file.
+paths: ["**/*.ts", "**/*.tsx"]
 disable-model-invocation: true
 ---
 
 # TypeScript best practices
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
-Apply `principle-type-system-discipline` first; read its `SKILL.md` at its absolute resource path.
+Apply the **type-system-discipline** principle skill first.
 
 | Rule | Summary |
 |------|---------|
@@ -23,12 +22,10 @@ Apply `principle-type-system-discipline` first; read its `SKILL.md` at its absol
 | Type guards | Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`. |
 | Exhaustiveness | Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added. |
 | `satisfies` over `as` | Validates the value without widening literal types. |
-| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See `principle-boundary-discipline`; read its `SKILL.md` at its absolute resource path. |
+| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See the **boundary-discipline** principle skill. |
 | Schema-derived types | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface. |
 | Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
 | Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
 | Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code. |
 
 Examples: `references/patterns.md`.
-
-This skill is explicit-invocation only. DSH does not consume a `paths` glob, so opening a `.ts` or `.tsx` file does not attach it: load it by name when you want it applied.

package/{assets → dist/pstack}/skills/why/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: why
-description: Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
+description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior."
 disable-model-invocation: true
 ---
 
 # Why
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
-Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works; read its `SKILL.md` at its absolute resource path when you need it. `why` answers what forces led to its shape.
+Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape.
 
-Each spawn below names a role key. `pstack_subagent` reads the route from `$DSH_HOME/pstack-models.md` on every delegation, and a role the file does not name inherits the parent route. Never invent a model id: this package cannot know which routes a deployment serves. An effort is different, because the target model advertises its own list and `pstack_subagent` checks your value against it and names the real values when it refuses, so predict no ladder beyond that. Read the Subagents section of the `poteto-mode` skill at its absolute resource path before you spawn anything. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
+Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
 
-Every spawn is `agent: "general"` with a brief that forbids writes. **Do not swap in a narrower preset or tool set.** A narrower set can drop MCP tools, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still must not write anything, and each brief says so; that rule is an instruction, not a sandbox, so check `git status` before believing a report.
+Every spawn is `generalPurpose` with `readonly: false` (agent mode). **Do not use readonly/Ask mode.** It strips MCP access, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still shouldn't write anything.
 
 ## Operating Posture
 
@@ -34,7 +34,7 @@ Before spawning investigators, build the seed context inline: file paths and lin
 
 ### Discovery
 
-Before spawning investigators, list the tools this Session actually has, and treat an MCP as available only when its own tools appear in that list. The DSH harness exposes no MCP directory to inspect, and this port does not read one: an MCP that is absent from the tool list is a recorded gap, never a guess.
+Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers.
 
 Map each available MCP to one evidence category:
 
@@ -48,7 +48,7 @@ Map each available MCP to one evidence category:
 
 Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.
 
-Spawn one investigator per category that has a matching MCP, all in one batch of `pstack_subagent` calls so they start together, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. Use `role: "why investigators"`. Each call returns a child id and the reports arrive as completion notices, so nothing polls and the synthesizer waits for every investigator that was started.
+Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `model`: the `why investigators` line, default `grok-4.7-xhigh-fast`.
 
 Each investigator's prompt is `references/investigator-prompt.md` filled in, plus:
 - the category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`
@@ -78,7 +78,7 @@ If your scope assessment suggests a single-commit trivial target where the PR de
 
 ## Step 4. Synthesize
 
-Spawn one synthesizer with `role: "why synthesizer"`. It gets:
+Spawn one synthesizer. `model`: the `why synthesizer` line, default `claude-opus-5-5-xhigh`. It gets:
 1. The investigator findings, including any null results and any categories skipped with justification
 2. The code anchor
 3. The user's original question

package/dist/script.d.mts

@@ -1,15 +1,11 @@
-import { a as JobsHost, g as ToolDefinition, i as JobId, o as JsonSchemaNode, u as SessionId, v as ToolsHost, y as WorkingDirectoryHost } from "./host-contract-o47JH_r8.mjs";
-//#region src/script.d.ts
+import { _ as ToolsHost, a as JobsHost, c as SessionId, g as ToolDefinition, i as JobId, o as JsonSchemaNode, v as WorkingDirectoryHost } from "./host-contract-CUPSpeNk.mjs";
 /** Model-facing tool name. */
 export declare const TOOL_NAME = "pstack_script";
 /** The shipped scripts this tool may run, in display order. */
 export declare const SCRIPT_IDS: string[];
 export type ScriptId = (typeof SCRIPT_IDS)[number];
-/** Default wall-clock limit for a foreground run. */
 export declare const DEFAULT_TIMEOUT_MS = 120000;
-/** Bounds a caller may set for one foreground run. */
 export declare const MAX_TIMEOUT_MS = 600000;
-/** Default cap on captured bytes per stream. */
 export declare const DEFAULT_OUTPUT_LIMIT_BYTES: number;
 /** Raised for an argument problem, before anything is spawned. */
 export declare class ScriptInputError extends Error {
@@ -19,7 +15,6 @@ export declare class ScriptInputError extends Error {
 export declare class ScriptMissingError extends Error {
   constructor(message: string);
 }
-/** One parsed call. */
 export interface ScriptArgs {
   readonly id: ScriptId;
   readonly args: readonly string[];
@@ -28,7 +23,6 @@ export interface ScriptArgs {
   readonly timeoutMs?: number;
   readonly outputLimitBytes?: number;
 }
-/** What a foreground run produced. */
 export interface ScriptResult {
   readonly kind: "foreground";
   readonly id: ScriptId;
@@ -37,74 +31,35 @@ export interface ScriptResult {
   readonly timedOut: boolean;
   readonly stdout: string;
   readonly stderr: string;
-  /** True when a stream was cut off at the limit. */
   readonly stdoutTruncated: boolean;
   readonly stderrTruncated: boolean;
   readonly durationMs: number;
 }
-/** What a background run produced. */
 export interface ScriptJobResult {
   readonly kind: "background";
   readonly id: ScriptId;
   readonly jobId: JobId;
   readonly status: string;
 }
-/** Either outcome, as the model sees it. */
 export type ScriptOutcome = ScriptResult | ScriptJobResult;
 /** Absolute path of one shipped artefact. */
 export declare function scriptPath(id: ScriptId): string;
-/**
- * The environment a child gets.
- *
- * The one rule is the Electron selector. Under Electron, `process.execPath` is the
- * Desktop binary, which starts a browser window unless `ELECTRON_RUN_AS_NODE=1` tells
- * it to behave as Node. Under plain Node the variable is inert — Node ignores it —
- * so setting it unconditionally would also work; it is conditional here so the
- * environment of a normal run stays exactly the caller's, and the one code path that
- * needs it is visible.
- */
+/** The environment a child gets: the Electron selector, and otherwise the caller's. */
 export declare function scriptEnvironment(base?: NodeJS.ProcessEnv, versions?: {
   readonly electron?: string;
 }): NodeJS.ProcessEnv;
 /** Validate the raw tool arguments. */
 export declare function parseScriptArgs(raw: unknown): ScriptArgs;
-/**
- * Resolve the directory the child runs in.
- *
- * The tool's `cwd` argument is documented as resolving against "this session's
- * directory", so `sessionCwd` — the value `ctx.workingDirectory.ensure()` returns —
- * is the base, not the Host process's working directory.
- *
- * - omitted           -> the session directory
- * - relative          -> joined onto the session directory
- * - absolute          -> used as-is
- *
- * With no Session (a call outside an Agent) there is no session directory to
- * anchor to; the argument is then passed through and `resolve` normalises it
- * against the Host process, which is the only directory that exists.
- */
+/** Resolve the directory the child runs in, relative to the caller-established session directory. */
 export declare function resolveWorkingDirectory(requested: string | undefined, sessionCwd: string | undefined): string | undefined;
-/**
- * Run one script in the foreground.
- *
- * A nonzero exit, a signal, a timeout, and truncated output are all returned rather
- * than raised: the caller needs to see what the script said before it failed, and an
- * exception would discard the captured output.
- */
+/** Run one script in the foreground. A nonzero exit, signal, timeout, and truncation are returned, not thrown. */
 export declare function runForeground(args: ScriptArgs, options?: {
   readonly execPath?: string;
   readonly environment?: NodeJS.ProcessEnv;
-  /** Already resolved by the caller; see `resolveWorkingDirectory`. */
   readonly cwd?: string;
   readonly signal?: AbortSignal;
 }): Promise<ScriptResult>;
-/**
- * Start a script as a background job.
- *
- * `jobs` is required and passing nothing is a refusal with a reason. A job whose
- * output nobody can read would be worse than a failed call: the model would report a
- * task as started and no notice would ever arrive.
- */
+/** Start a script as a background job. `jobs` absent is a refusal with a reason. */
 export declare function runBackground(args: ScriptArgs, options: {
   readonly jobs?: JobsHost | undefined;
   readonly caller?: SessionId;
@@ -112,82 +67,25 @@ export declare function runBackground(args: ScriptArgs, options: {
   readonly environment?: NodeJS.ProcessEnv;
   readonly cwd?: string;
 }): Promise<ScriptJobResult>;
-/**
- * Render one captured stream as a fenced block, byte for byte.
- *
- * `trimEnd` used to run here, which is wrong for two reasons:
- *
- * - A stream of only whitespace passed the `!== ""` test and then rendered as an
- *   empty-looking `stdout:` line, so a reader concluded the script printed nothing.
- * - `check-plan`'s contract includes exact line counts and blank-line separators, so
- *   a trimmed block is a different document — and the model reads this text as the
- *   script's output.
- *
- * A fence keeps every byte visible, including trailing blank lines. The fence is
- * lengthened past the longest backtick run in the content so it can never be closed
- * early by the content itself. Nothing inside is escaped or reinterpreted.
- */
+/** Render one captured stream as a fence that the content cannot close early. */
 export declare function renderCapturedStream(text: string): readonly string[];
 /** Render one outcome for the model. */
 export declare function renderScriptOutcome(outcome: ScriptOutcome): string;
-/** The model-facing JSON Schema for `parameters`. */
 export declare function buildScriptParameters(): Record<string, unknown>;
-/**
- * The declared shape of one outcome, exported so tests can validate real results.
- *
- * Split by `kind` instead of one flat object. The flat form could only require
- * `kind` and `id`, so a foreground result that omitted `exitCode` was still
- * "valid" and the schema proved nothing about the fields the model reads.
- *
- * `signal` is nullable because `child_process` reports `null` whenever the child
- * exited on its own — that is every successful run. Declaring it `string` made
- * the registry reject the tool's own normal output: `createSuccessResult()`
- * validates before rendering, so **every** clean exit surfaced to the model as
- * `tool "pstack_script" returned invalid output`.
- */
 export declare const OUTPUT_SCHEMA: JsonSchemaNode;
 /** The slices of the Cordis context this tool needs. */
 export interface PstackScriptHost {
   readonly tools: ToolsHost;
-  /** Resolves the Session's current directory; see `WorkingDirectoryHost`. */
   readonly workingDirectory: WorkingDirectoryHost;
-  /**
-   * Optional, and read per call rather than snapshotted.
-   *
-   * A profile may mount a job controller after this row, so a value read once in
-   * `apply` would stay `undefined` forever. `ctx.get("jobs")` is rc.3's
-   * optional-service read: it returns `undefined` instead of throwing when the
-   * service is absent, which is why `jobs` is not declared in `inject`.
-   */
   readonly getJobs?: () => JobsHost | undefined;
 }
 /** Build the tool for one row. */
 export declare function createPstackScriptTool(host: PstackScriptHost): ToolDefinition;
 /** Cordis row name, used by Loader diagnostics. */
 export declare const name = "pstack-script";
-/**
- * The hard dependencies.
- *
- * `tools` is the registry this row registers into; `workingDirectory` is what
- * turns the tool's `cwd` argument and its omitted case into the Session's
- * directory. Both are always present in a profile that has an Agent at all.
- *
- * `jobs` is deliberately absent: a composition without a job controller still
- * registers the tool, and only `background: true` is refused. Declaring `jobs`
- * here would keep the whole fiber inactive in every profile that has no job
- * controller, which is most of them.
- */
+/** Hard dependencies: the tool registry and the session directory. `jobs` is optional and read per call. */
 export declare const inject: string[];
-/**
- * Register `pstack_script` for this row.
- *
- * `inject` is what makes `ctx.tools` readable at all: without it Cordis runs
- * `apply` immediately and the service proxy throws
- * `cannot get property "tools" without inject`, so the row would register nothing
- * in any profile.
- */
+/** Register `pstack_script` for this row. */
 export declare function apply(ctx: PstackScriptHost & {
   get?: (name: string) => JobsHost | undefined;
-}): void;
-//#endregion
-//# sourceMappingURL=script.d.mts.map
+}): void;