@skill-harness/core 0.1.2 → 0.3.0

package/dist/sources.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * What a run measured, as a map of `key -> sha256`, recorded in results.yaml so
+ * lint can prove a published result still describes the current inputs.
+ *
+ * A run measures more than the skill text. It measures the SKILL.md, any agent
+ * file, **the scenario definition itself** (turns, checklist, gates) and **the
+ * fixture** the scenario starts from. Hashing only the first two — which is what
+ * shipped through 0.2.1 — meant editing a checklist or swapping a fixture left
+ * every published result looking current.
+ *
+ * ## Key scheme
+ *
+ * | key | means |
+ * |---|---|
+ * | `SKILL.md` | the skill text, resolved against the skill dir |
+ * | `scenario:<id>` | the semantic content of one scenario in the spec |
+ * | `fixture:<path>` | every file under one fixture dir |
+ * | anything else | a file path resolved against the spec's dir (`system_prompt_file`) |
+ *
+ * Separation from bare-path keys is conventional, not guaranteed: `scenario:A1`
+ * is a legal POSIX filename, so nothing stops someone naming an agent file that.
+ * In practice `system_prompt_file` and `post_test` values are ordinary relative
+ * paths, and a `<name>:` prefix is reserved for this scheme. Old results carrying
+ * only bare-path keys keep resolving exactly as before.
+ *
+ * ## Why per-scenario, not one hash of specification.yaml
+ *
+ * Hashing the whole spec file would mark **every** historical run stale the
+ * moment a spec grows by one scenario — the precise noise `lint`'s scenario-set
+ * check already exists to prevent ("a spec reshape must not consistency-flag
+ * every historical run"). A per-scenario digest says what actually changed:
+ * editing A1's checklist marks A1 stale and leaves A2 alone; appending a new
+ * scenario marks nothing stale, because nothing already measured changed.
+ *
+ * It also ignores formatting: the digest is built from the *parsed* scenario, so
+ * reindenting the YAML or reordering scenarios is correctly a no-op, while
+ * changing a single checklist word is correctly a change.
+ */
+export const SCENARIO_PREFIX = "scenario:";
+export const FIXTURE_PREFIX = "fixture:";
+/**
+ * Recorded in place of a hash when a source existed but could not be read.
+ *
+ * Omitting it instead — which is what an early version did — is the worst
+ * available option: `lint` only ever iterates the keys a run recorded, so a
+ * source dropped at record time is never compared again for the life of that
+ * result. A fixture briefly unreadable during a run could then be replaced
+ * wholesale and `lint` would still report 0 findings, which is verbatim the miss
+ * this module was written to close.
+ *
+ * Not valid sha256 hex, so it can never equal a real digest and always surfaces.
+ */
+export const UNREADABLE = "unreadable";
+/** sha256 of a file, or null when it doesn't exist / isn't readable. */
+export function fileSha256(path) {
+    try {
+        return createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stable sha256 over a directory tree: every file's relative path (POSIX-slashed,
+ * sorted) and contents. Null if the directory is missing or unreadable.
+ *
+ * Sorting is what makes it stable — readdir order is filesystem-dependent, so an
+ * unsorted walk would produce different digests for identical trees on different
+ * machines and turn CI into a staleness alarm. Paths are hashed alongside
+ * contents so that renaming a fixture file is a change, and separators are
+ * normalised so a Linux-recorded hash still matches on Windows.
+ */
+export function dirSha256(dir) {
+    let files;
+    try {
+        files = walk(dir).sort();
+    }
+    catch {
+        return null;
+    }
+    const h = createHash("sha256");
+    for (const rel of files) {
+        h.update(rel);
+        h.update("\0");
+        try {
+            h.update(readFileSync(join(dir, rel)));
+        }
+        catch {
+            return null; // a file that vanished mid-walk makes the whole digest untrustworthy
+        }
+        h.update("\0");
+    }
+    return h.digest("hex");
+}
+/** Relative POSIX paths of every file under `dir`, recursively. Throws if `dir` is unreadable. */
+function walk(dir, prefix = "") {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+            out.push(...walk(join(dir, e.name), rel));
+        }
+        else if (e.isFile()) {
+            out.push(rel);
+        }
+        // symlinks/sockets/etc. are deliberately skipped: a fixture is plain files,
+        // and following links could hash something outside the fixture entirely.
+    }
+    return out;
+}
+/**
+ * A scenario's semantic digest: everything that changes what the scenario
+ * measures, and nothing that doesn't.
+ *
+ * Built from the parsed scenario rather than its YAML text, so formatting is
+ * irrelevant. `critical` is included because it changes whether the scenario can
+ * block a ship; `title` is included because it is what a reader of the scorecard
+ * believes was tested.
+ */
+export function scenarioDigest(s) {
+    // Destructured, with the remainder pinned to `Record<string, never>`, so that
+    // adding a field to `Scenario` or `SeededAssert` FAILS THE BUILD here instead of
+    // silently escaping the digest. A field nobody remembered to add is a permanent
+    // staleness blind spot — edit it and every published result still looks current,
+    // which is precisely the bug this module exists to kill. This PR added two
+    // SeededAssert fields and remembered both; that only proves the discipline works
+    // while someone is looking, so the compiler now does the looking.
+    const { id, title, critical, mode, turns, checklist, fixture, assert, workspace, remote, systemPromptFile, reps, passThreshold, ...restScenario } = s;
+    const _scenarioExhaustive = restScenario;
+    void _scenarioExhaustive;
+    const { vitest, diff_contains, diff_excludes, post_test, ...restAssert } = assert ?? {};
+    const _assertExhaustive = restAssert;
+    void _assertExhaustive;
+    const canonical = JSON.stringify([
+        id,
+        title,
+        critical,
+        mode,
+        turns,
+        checklist,
+        fixture ?? null,
+        assert ? [vitest ?? null, diff_contains ?? null, diff_excludes ?? null, post_test ?? null] : null,
+        workspace,
+        remote,
+        systemPromptFile ?? null,
+        reps ?? null,
+        passThreshold ?? null,
+    ]);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** Absolute path a fixture key refers to. Fixtures resolve against the spec's dir, like workspace.ts. */
+function fixtureAbs(specDir, fixture) {
+    return isAbsolute(fixture) ? fixture : resolve(specDir, fixture);
+}
+/**
+ * The fixture path a scenario actually runs in, or undefined.
+ *
+ * The EFFECTIVE workspace fixture, which is not always `scenario.fixture`: an
+ * inline scenario with `env.workspace: fixture:PATH` sets `workspace.fixture`
+ * and leaves `scenario.fixture` unset. Exported and shared with lint, which
+ * needs the identical rule — a second copy of this expression is how the hashed
+ * set and the checked set drift apart.
+ */
+export function effectiveFixture(s) {
+    return typeof s.workspace === "object" && s.workspace !== null ? s.workspace.fixture : undefined;
+}
+/**
+ * Hash every source this run measures: SKILL.md, each distinct
+ * `system_prompt_file`, each scenario's definition, and each distinct fixture
+ * tree. Entries that can't be read are omitted — a missing source is lint's
+ * problem to report, not run's to crash on.
+ */
+export function sourceHashes(ctx) {
+    const hashes = {};
+    // UNREADABLE rather than omission on every branch below: a source we failed to
+    // hash must stay visible to lint, not vanish from the record. See UNREADABLE.
+    hashes["SKILL.md"] = fileSha256(resolve(ctx.skillDir, "SKILL.md")) ?? UNREADABLE;
+    for (const s of ctx.scenarios) {
+        hashes[SCENARIO_PREFIX + s.id] = scenarioDigest(s);
+        if (s.systemPromptFile && !(s.systemPromptFile in hashes)) {
+            hashes[s.systemPromptFile] = fileSha256(resolve(ctx.specDir, s.systemPromptFile)) ?? UNREADABLE;
+        }
+        // The post-test IS the gate on a post_test scenario, and it lives outside the
+        // fixture tree by convention (`fixture: fixtures/A1`, `post_test: post/A1.test.ts`),
+        // so neither the fixture digest nor the scenario digest — which holds only the
+        // path string — covers its contents. Tightening an assertion in it changes what
+        // the scorecard measured; without this it would change nothing lint can see.
+        const pt = s.assert?.post_test;
+        if (pt && !(pt in hashes)) {
+            hashes[pt] = fileSha256(isAbsolute(pt) ? pt : resolve(ctx.specDir, pt)) ?? UNREADABLE;
+        }
+        const fx = effectiveFixture(s);
+        if (fx && !(FIXTURE_PREFIX + fx in hashes)) {
+            hashes[FIXTURE_PREFIX + fx] = dirSha256(fixtureAbs(ctx.specDir, fx)) ?? UNREADABLE;
+        }
+    }
+    return hashes;
+}
+/**
+ * The current hash for a recorded key, or null when the source is gone.
+ *
+ * `undefined` is distinct from `null` and means "not comparable": the key names a
+ * scenario the spec no longer has. That is a spec *reshape*, not staleness — the
+ * same stance lint's scenario-set check already takes — so the caller stays quiet
+ * rather than reporting a removed scenario as a stale measurement.
+ *
+ * Sharing this resolver with `sourceHashes` is what keeps recording and checking
+ * from drifting: a new key kind is defined once, for both sides.
+ */
+export function currentHashFor(key, ctx) {
+    if (key === "SKILL.md")
+        return fileSha256(resolve(ctx.skillDir, "SKILL.md"));
+    if (key.startsWith(SCENARIO_PREFIX)) {
+        const id = key.slice(SCENARIO_PREFIX.length);
+        const s = ctx.scenarios.find((x) => x.id === id);
+        return s ? scenarioDigest(s) : undefined; // removed → reshape, not stale
+    }
+    if (key.startsWith(FIXTURE_PREFIX)) {
+        return dirSha256(fixtureAbs(ctx.specDir, key.slice(FIXTURE_PREFIX.length)));
+    }
+    // A prefixed key this version doesn't know is written by a NEWER skill-harness.
+    // Falling through to the path branch would resolve `agent:foo` as a filename,
+    // find nothing, and report a confident "agent:foo no longer exists" — a wrong
+    // finding about a source that is fine. Not comparable is the honest answer.
+    if (/^[a-z][a-z0-9-]*:/.test(key))
+        return undefined;
+    return fileSha256(resolve(ctx.specDir, key)); // system_prompt_file, post_test
+}
+/** Human label for a recorded key, used in lint messages. */
+export function describeSourceKey(key) {
+    if (key.startsWith(SCENARIO_PREFIX))
+        return `scenario \`${key.slice(SCENARIO_PREFIX.length)}\``;
+    if (key.startsWith(FIXTURE_PREFIX))
+        return `fixture \`${key.slice(FIXTURE_PREFIX.length)}\``;
+    return key;
+}
+/** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
+export function scenarioIdForKey(key, scenarios) {
+    if (key.startsWith(SCENARIO_PREFIX))
+        return key.slice(SCENARIO_PREFIX.length);
+    if (key.startsWith(FIXTURE_PREFIX)) {
+        const fx = key.slice(FIXTURE_PREFIX.length);
+        const owners = scenarios.filter((s) => effectiveFixture(s) === fx);
+        // Only attribute a shared fixture to a scenario when exactly one owns it —
+        // naming an arbitrary one of several would misdirect the re-run.
+        return owners.length === 1 ? owners[0].id : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=sources.js.map

package/dist/spec.d.ts

@@ -3,6 +3,21 @@ export type ScenarioMode = "inline" | "seeded";
 export interface SeededAssert {
     vitest?: boolean;
     diff_contains?: string[];
+    /**
+     * Needles that must NOT appear in the staged diff. The negative twin of
+     * diff_contains: it makes a scope-discipline requirement ("fix sliceRange, do
+     * not touch lastIndex") objective instead of something the judge has to infer
+     * from the model's prose.
+     */
+    diff_excludes?: string[];
+    /**
+     * A test file copied into the workspace AFTER the agent finishes, then run.
+     * The model never sees it, so it cannot write code shaped to pass it — this
+     * checks the behavior the task actually required. Orthogonal to `vitest`,
+     * which runs the model's OWN tests and therefore grades a claim the model
+     * gets to make about itself.
+     */
+    post_test?: string;
 }
 export interface Scenario {
     id: string;
@@ -14,6 +29,8 @@ export interface Scenario {
     fixture?: string;
     assert?: SeededAssert;
     workspace: WorkspaceKind;
+    remote: boolean;
+    systemPromptFile?: string;
     reps?: number;
     passThreshold?: number;
 }

package/dist/spec.js

@@ -54,6 +54,24 @@ function resolveWorkspace(env, mode, fixture, id, file) {
     }
     throw new SpecError(`scenario \`${id}\` env.workspace must be none | empty-git | fixture:<path>`, file);
 }
+/**
+ * Resolve `env.remote`. A remote needs a repo to attach to, so it is only meaningful
+ * with empty-git or a fixture — asking for one on a bare cwd is an authoring mistake,
+ * not something to silently ignore.
+ */
+function resolveRemote(env, workspace, id, file) {
+    const raw = env && typeof env === "object" ? env.remote : undefined;
+    if (raw === undefined)
+        return false;
+    if (typeof raw !== "boolean") {
+        throw new SpecError(`scenario \`${id}\` env.remote must be true or false`, file);
+    }
+    if (raw && workspace === "none") {
+        throw new SpecError(`scenario \`${id}\` sets env.remote but has no repo to attach it to — ` +
+            `use env.workspace: empty-git or fixture:<path>`, file);
+    }
+    return raw;
+}
 /** Parse + validate a specification.yaml from its raw text. `file` is used in error messages. */
 export function parseSpec(text, file) {
     let doc;
@@ -124,6 +142,7 @@ export function parseSpec(text, file) {
             turns: s.turns,
             checklist: s.checklist,
             workspace: "none",
+            remote: false,
         };
         if (mode === "seeded") {
             if (typeof s.fixture !== "string" || s.fixture.length === 0) {
@@ -139,12 +158,56 @@ export function parseSpec(text, file) {
                     if (!isStringArray(a.diff_contains)) {
                         throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_contains\` must be strings`, file);
                     }
+                    if (a.diff_contains.some((n) => n === "")) {
+                        // Every string contains "", so an empty positive needle makes the gate
+                        // pass on ANY diff, including an empty one. This is the more dangerous
+                        // twin of the diff_excludes check below: that one fails forever and gets
+                        // investigated, this one passes forever and nobody ever looks.
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_contains\` contains an empty string — it would match every diff, so the gate could never fail`, file);
+                    }
                     assertObj.diff_contains = a.diff_contains;
                 }
+                if (a.diff_excludes !== undefined) {
+                    if (!isStringArray(a.diff_excludes)) {
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_excludes\` must be strings`, file);
+                    }
+                    if (a.diff_excludes.some((n) => n === "")) {
+                        // "" is in every string, so the gate could never pass — and the failure
+                        // would read as a mysterious diff problem rather than a spec typo.
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_excludes\` contains an empty string — it would match every diff`, file);
+                    }
+                    assertObj.diff_excludes = a.diff_excludes;
+                }
+                // A needle required AND forbidden can never pass. Catching it here turns a
+                // scenario that always fails for an invisible reason into an authoring error.
+                const both = (assertObj.diff_contains ?? []).filter((n) => (assertObj.diff_excludes ?? []).includes(n));
+                if (both.length > 0) {
+                    throw new SpecError(`seeded scenario \`${id}\` lists ${both.map((n) => JSON.stringify(n)).join(", ")} in both ` +
+                        `\`assert.diff_contains\` and \`assert.diff_excludes\` — the gate could never pass`, file);
+                }
+                if (a.post_test !== undefined) {
+                    if (typeof a.post_test !== "string" || !a.post_test.trim()) {
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.post_test\` must be a non-empty path`, file);
+                    }
+                    assertObj.post_test = a.post_test.trim();
+                }
                 scenario.assert = assertObj;
             }
         }
         scenario.workspace = resolveWorkspace(s.env, mode, scenario.fixture, id, file);
+        scenario.remote = resolveRemote(s.env, scenario.workspace, id, file);
+        if (s.system_prompt_file !== undefined) {
+            if (typeof s.system_prompt_file !== "string" || !s.system_prompt_file.trim()) {
+                throw new SpecError(`scenario \`${id}\` \`system_prompt_file\` must be a non-empty string`, file);
+            }
+            // A subagent has no turn two. Testing an agent file across multiple turns would
+            // measure conversation armor the single-shot contract deliberately drops.
+            if (scenario.turns.length !== 1) {
+                throw new SpecError(`scenario \`${id}\` uses system_prompt_file, so it must have exactly one turn ` +
+                    `(got ${scenario.turns.length}) — an agent definition is single-shot by contract`, file);
+            }
+            scenario.systemPromptFile = s.system_prompt_file.trim();
+        }
         if (s.reps !== undefined) {
             if (typeof s.reps !== "number" || !Number.isInteger(s.reps) || s.reps < 1) {
                 throw new SpecError(`scenario \`${id}\` \`reps\` must be a positive integer`, file);

package/dist/util/env.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Environment-variable resolution for the `SKILL_HARNESS_*` namespace.
+ *
+ * The tuning vars predate the skill-check → skill-harness rename and shipped in
+ * 0.1.x under a `SKILL_CHECK_` prefix. Anyone who set one of those in a shell
+ * profile or CI config must keep working, so every name is resolved new-first
+ * with a legacy fallback and a one-time notice pointing at the new spelling.
+ *
+ * Call these with the *suffix* only (`"PI_TIMEOUT_MS"`), never a full name — the
+ * prefixes are this module's business, which is what keeps ROADMAP rule 5 (no
+ * new `SKILL_CHECK_*` names) enforceable by grepping for the prefix.
+ */
+/** Test seam: clears the once-per-suffix warning memo. */
+export declare function __resetEnvWarnings(): void;
+/**
+ * Resolve `SKILL_HARNESS_<suffix>`, falling back to `SKILL_CHECK_<suffix>`.
+ *
+ * An empty value counts as unset: exporting a var as `""` is a common way to
+ * neutralize it in CI, and honoring it as "set" would make the legacy fallback
+ * unreachable for exactly those users.
+ */
+export declare function readEnv(suffix: string): string | undefined;
+/**
+ * Resolve a positive-integer var, e.g. a timeout in ms.
+ *
+ * A set-but-unparseable value warns and yields `fallback` rather than passing
+ * `NaN` down: the pre-rename `Number(process.env.X ?? default)` turned a typo
+ * into a NaN timeout, which silently disabled the timeout it was feeding.
+ */
+export declare function envNum(suffix: string, fallback: number): number;
+/** Resolve a boolean var: any non-empty value is on. */
+export declare function envFlag(suffix: string): boolean;

package/dist/util/env.js

@@ -0,0 +1,67 @@
+/**
+ * Environment-variable resolution for the `SKILL_HARNESS_*` namespace.
+ *
+ * The tuning vars predate the skill-check → skill-harness rename and shipped in
+ * 0.1.x under a `SKILL_CHECK_` prefix. Anyone who set one of those in a shell
+ * profile or CI config must keep working, so every name is resolved new-first
+ * with a legacy fallback and a one-time notice pointing at the new spelling.
+ *
+ * Call these with the *suffix* only (`"PI_TIMEOUT_MS"`), never a full name — the
+ * prefixes are this module's business, which is what keeps ROADMAP rule 5 (no
+ * new `SKILL_CHECK_*` names) enforceable by grepping for the prefix.
+ */
+const NEW_PREFIX = "SKILL_HARNESS_";
+const LEGACY_PREFIX = "SKILL_CHECK_";
+/** Suffixes already warned about, so a module-scope read doesn't nag per call. */
+const warned = new Set();
+/** Test seam: clears the once-per-suffix warning memo. */
+export function __resetEnvWarnings() {
+    warned.clear();
+}
+function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    process.stderr.write(`skill-harness: ${message}\n`);
+}
+/**
+ * Resolve `SKILL_HARNESS_<suffix>`, falling back to `SKILL_CHECK_<suffix>`.
+ *
+ * An empty value counts as unset: exporting a var as `""` is a common way to
+ * neutralize it in CI, and honoring it as "set" would make the legacy fallback
+ * unreachable for exactly those users.
+ */
+export function readEnv(suffix) {
+    const fresh = process.env[NEW_PREFIX + suffix];
+    if (fresh)
+        return fresh;
+    const legacy = process.env[LEGACY_PREFIX + suffix];
+    if (legacy) {
+        warnOnce(`legacy:${suffix}`, `${LEGACY_PREFIX}${suffix} is the pre-rename name and still honored; rename it to ${NEW_PREFIX}${suffix}.`);
+        return legacy;
+    }
+    return undefined;
+}
+/**
+ * Resolve a positive-integer var, e.g. a timeout in ms.
+ *
+ * A set-but-unparseable value warns and yields `fallback` rather than passing
+ * `NaN` down: the pre-rename `Number(process.env.X ?? default)` turned a typo
+ * into a NaN timeout, which silently disabled the timeout it was feeding.
+ */
+export function envNum(suffix, fallback) {
+    const raw = readEnv(suffix);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        warnOnce(`malformed:${suffix}`, `${NEW_PREFIX}${suffix}=${JSON.stringify(raw)} is not a positive number; using ${fallback}.`);
+        return fallback;
+    }
+    return n;
+}
+/** Resolve a boolean var: any non-empty value is on. */
+export function envFlag(suffix) {
+    return readEnv(suffix) !== undefined;
+}
+//# sourceMappingURL=env.js.map

package/dist/workspace.d.ts

@@ -6,12 +6,44 @@ export interface Workspace {
     cwd: string;
     cleanup(): void;
 }
+export declare const MARKERS: string[];
+/**
+ * Top-level directories in a fixture that claim to be markers but aren't one.
+ *
+ * A misspelled marker (`_uncommited/`) used to be copied into the baseline commit as a
+ * literal directory: the tree came up clean, the scenario silently measured the opposite
+ * of its intent, and nothing reported it. Any top-level `_name/` is therefore treated as
+ * a marker claim and must be a real one.
+ *
+ * The predicate is `_` followed by a LETTER, so `__tests__` and `__pycache__` — ordinary
+ * directories a fixture may legitimately contain — are not marker claims, and neither are
+ * oddities like `_2fa/` or `_-tmp/`, which no marker could plausibly be mistaken for.
+ * Nested `pkg/_staged/` is likewise ordinary content: markers are top-level only.
+ *
+ * Exported so `lint` can report the same set this module refuses to run. If the two
+ * disagreed, lint would hand out a clean bill of health for a fixture the runtime then
+ * rejects — which is worse than not checking at all.
+ */
+export declare function unknownMarkerDirs(src: string): string[];
+/**
+ * The known marker a misspelling was probably reaching for, or null.
+ *
+ * Case-insensitive within an edit distance of 2 — enough for `_uncommited` (one
+ * dropped `t`), `_Staged` (case) and `_uncommmitted` (doubled letter), while
+ * `_fixtures` or `_helpers` correctly suggest nothing rather than a confident
+ * wrong guess.
+ */
+export declare function suggestMarker(name: string): string | null;
 /**
  * Create an isolated temp-dir working directory for one scenario. `none` is an
  * empty dir (no git); `empty-git` initialises a clean repo; `{ fixture }` copies
  * the fixture (relative paths resolve against `specDir`) then initialises a repo
- * with a baseline commit. Child processes run here, never in the user's home.
+ * with a baseline commit. A fixture may carry top-level `_staged/` and
+ * `_uncommitted/` subdirectories, applied after that commit to start the scenario
+ * from a dirty tree. `opts.remote` additionally wires a local bare `origin`.
+ * Child processes run here, never in the user's home.
  */
 export declare function createWorkspace(kind: WorkspaceKind, opts: {
     specDir: string;
+    remote?: boolean;
 }): Workspace;