okstra 0.174.0 → 0.176.0

package/{src → dist}/commands/report/translate.mjs

@@ -1,5 +1,4 @@
 import { runInstalledScript } from "../../lib/python-helper.mjs";
-
 const USAGE = `okstra report-translate — build and verify a final-report translation sidecar
 
 A thin spawn shim over \`scripts/okstra-report-translate.py\` (installed at
@@ -21,11 +20,11 @@ Usage:
       and report what is still English. Exits non-zero on a pointer that
       resolves nowhere — the translator's own gate before it returns.
 `;
-
 export async function run(args) {
-  return runInstalledScript({
-    scriptName: "okstra-report-translate.py",
-    args,
-    usage: USAGE,
-  });
+    return runInstalledScript({
+        scriptName: "okstra-report-translate.py",
+        args,
+        usage: USAGE,
+    });
 }
+//# sourceMappingURL=translate.mjs.map

package/dist/commands/report/translate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.mjs","sourceRoot":"","sources":["../../../src/commands/report/translate.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;CAoBb,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAuB;IAC/C,OAAO,kBAAkB,CAAC;QACxB,UAAU,EAAE,4BAA4B;QACxC,IAAI;QACJ,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/helper-scripts.d.mts

@@ -0,0 +1,3 @@
+export declare const HELPER_SCRIPT_NAMES: readonly string[];
+import type { RuntimePaths } from "./types.mjs";
+export declare function missingHelperScripts(paths: RuntimePaths, resolve: (paths: RuntimePaths, name: string) => string | null): string[];

package/{src → dist}/lib/helper-scripts.mjs

@@ -4,21 +4,18 @@
 // environment gate instead of at the blocking lead step that calls it mid-run.
 // A contract test keeps this list in step with the `scriptName:` literals in
 // src/commands/**.
-
 export const HELPER_SCRIPT_NAMES = Object.freeze([
-  "okstra-error-log.py",
-  "okstra-incremental-carry.py",
-  "okstra-incremental-scope.py",
-  "okstra-inject-report-index.py",
-  "okstra-render-final-report.py",
-  "okstra-render-report-views.py",
-  "okstra-report-translate.py",
-  "okstra-spawn-followups.py",
-  "okstra-token-usage.py",
+    "okstra-error-log.py",
+    "okstra-incremental-carry.py",
+    "okstra-incremental-scope.py",
+    "okstra-inject-report-index.py",
+    "okstra-render-final-report.py",
+    "okstra-render-report-views.py",
+    "okstra-report-translate.py",
+    "okstra-spawn-followups.py",
+    "okstra-token-usage.py",
 ]);
-
-// `resolve` is the same resolver the wrappers call, so preflight cannot pass a
-// script the dispatch path would then fail to find.
 export function missingHelperScripts(paths, resolve) {
-  return HELPER_SCRIPT_NAMES.filter((name) => !resolve(paths, name));
+    return HELPER_SCRIPT_NAMES.filter((name) => !resolve(paths, name));
 }
+//# sourceMappingURL=helper-scripts.mjs.map

package/dist/lib/helper-scripts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-scripts.mjs","sourceRoot":"","sources":["../../src/lib/helper-scripts.mts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,mBAAmB;AAEnB,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,qBAAqB;IACrB,6BAA6B;IAC7B,6BAA6B;IAC7B,+BAA+B;IAC/B,+BAA+B;IAC/B,+BAA+B;IAC/B,4BAA4B;IAC5B,2BAA2B;IAC3B,uBAAuB;CACxB,CAAC,CAAC;AAMH,MAAM,UAAU,oBAAoB,CAClC,KAAmB,EACnB,OAA6D;IAE7D,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC"}

package/dist/lib/host-registry-client.d.mts

@@ -0,0 +1,25 @@
+import type { HostProbeOptions, HostReadiness, HostRegistryCatalog, HostResolveOptions, HostRuntimeResolution, PythonRunner } from "./types.mjs";
+export declare const RUNTIME_AUTO = "auto";
+export declare class HostRegistryClientError extends Error {
+    constructor(message: string);
+}
+export declare function createHostRegistryClient({ runPython }?: {
+    readonly runPython?: PythonRunner;
+}): {
+    readonly catalog: () => Promise<HostRegistryCatalog>;
+    readonly resolveHostRuntime: (options: HostResolveOptions) => Promise<HostRuntimeResolution>;
+    readonly probeHost: (options: HostProbeOptions) => Promise<HostReadiness>;
+};
+export declare function normalizeHostRequest(value: unknown): string;
+export declare function loadHostCatalog(): Promise<HostRegistryCatalog>;
+export declare function resolveHostRuntime(options: HostResolveOptions): Promise<HostRuntimeResolution>;
+export declare function probeHost(options: HostProbeOptions): Promise<HostReadiness>;
+export declare function resolveRuntime({ requestedRuntime, command, env, capabilities, }?: HostResolveOptions): Promise<HostRuntimeResolution>;
+export declare function checkRuntimeReadiness({ runtime, projectRoot, homeDir, hostRegistryClient, }: {
+    readonly runtime?: string;
+    readonly projectRoot: string;
+    readonly homeDir?: string;
+    readonly hostRegistryClient?: {
+        readonly probeHost: (options: HostProbeOptions) => Promise<HostReadiness>;
+    };
+}): Promise<HostReadiness>;

package/dist/lib/host-registry-client.mjs

@@ -0,0 +1,152 @@
+import { homedir } from "node:os";
+import { runPythonModule } from "./python-helper.mjs";
+export const RUNTIME_AUTO = "auto";
+const HOST_REQUEST_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const PLAIN_TEXT_INPUT = "plain_text_input";
+export class HostRegistryClientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostRegistryClientError";
+    }
+}
+async function callHosts(runPython, args) {
+    const result = await runPython({
+        module: "okstra_ctl.entrypoints.hosts",
+        args,
+        stdio: "capture",
+    });
+    if (result.code !== 0) {
+        const detail = String(result.stderr || "").trim() || `Python exited ${result.code}`;
+        throw new HostRegistryClientError(detail);
+    }
+    const stdout = String(result.stdout || "").trim();
+    if (!stdout)
+        throw new HostRegistryClientError("host registry returned empty stdout");
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new HostRegistryClientError(`host registry returned invalid JSON: ${message}`);
+    }
+}
+function resolutionContext(env = {}, capabilities = {}) {
+    return {
+        env: { OKSTRA_RUNTIME_HOST: String(env?.OKSTRA_RUNTIME_HOST ?? "") },
+        capabilities: {
+            claudeSkillHandoff: capabilities?.claudeSkillHandoff === true,
+            tmuxAvailable: capabilities?.tmuxAvailable === true,
+        },
+    };
+}
+export function createHostRegistryClient({ runPython = runPythonModule } = {}) {
+    return {
+        async catalog() {
+            return await callHosts(runPython, ["catalog", "--json"]);
+        },
+        async resolveHostRuntime({ requestedRuntime, command, env, capabilities }) {
+            return await callHosts(runPython, [
+                "resolve",
+                "--requested", requestedRuntime,
+                "--command", command,
+                "--context-json", JSON.stringify(resolutionContext(env, capabilities)),
+            ]);
+        },
+        async probeHost({ hostRuntime, entryMode, projectRoot, homeDir, availableFunctions = [], }) {
+            const args = [
+                "probe",
+                "--host", hostRuntime,
+                "--entry-mode", entryMode,
+                "--project-root", projectRoot,
+                "--home-dir", homeDir,
+            ];
+            for (const availableFunction of availableFunctions) {
+                args.push("--available-function", availableFunction);
+            }
+            return await callHosts(runPython, args);
+        },
+    };
+}
+const hostRegistryClient = createHostRegistryClient();
+export function normalizeHostRequest(value) {
+    const runtime = String(value ?? "").trim() || RUNTIME_AUTO;
+    if (!HOST_REQUEST_PATTERN.test(runtime)) {
+        throw new Error(`invalid runtime '${runtime}' (expected auto, all, or a lowercase host ID)`);
+    }
+    return runtime;
+}
+function failedResolution(requestedRuntime, error) {
+    return {
+        ok: false,
+        requestedRuntime,
+        resolvedRuntime: null,
+        launchMode: null,
+        installTargets: [],
+        host: "unknown",
+        confidence: "low",
+        reason: error.message,
+        fallbackFrom: null,
+        warnings: [],
+    };
+}
+function catalogResolution(catalog) {
+    const hosts = Array.isArray(catalog?.hosts) ? catalog.hosts : [];
+    const catalogHostIds = hosts.map((host) => host.id);
+    const installTargets = Array.from(new Set(hosts.flatMap((host) => host.install_targets ?? host.installTargets ?? []))).sort();
+    return {
+        ok: true,
+        requestedRuntime: "all",
+        resolvedRuntime: "all",
+        launchMode: "catalog",
+        installTargets,
+        catalogHostIds,
+        host: "explicit",
+        confidence: "high",
+        reason: "All registered host runtimes requested.",
+        fallbackFrom: null,
+        warnings: [],
+    };
+}
+export async function loadHostCatalog() {
+    return await hostRegistryClient.catalog();
+}
+export async function resolveHostRuntime(options) {
+    return await hostRegistryClient.resolveHostRuntime(options);
+}
+export async function probeHost(options) {
+    return await hostRegistryClient.probeHost(options);
+}
+export async function resolveRuntime({ requestedRuntime = RUNTIME_AUTO, command = "run", env = {}, capabilities = {}, } = {
+    requestedRuntime: RUNTIME_AUTO,
+    command: "run",
+}) {
+    const request = normalizeHostRequest(requestedRuntime);
+    try {
+        if (request === "all")
+            return catalogResolution(await loadHostCatalog());
+        return await resolveHostRuntime({
+            requestedRuntime: request,
+            command,
+            env,
+            capabilities,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof HostRegistryClientError))
+            throw error;
+        return failedResolution(request, error);
+    }
+}
+export async function checkRuntimeReadiness({ runtime, projectRoot, homeDir = homedir(), hostRegistryClient = { probeHost }, }) {
+    if (!runtime)
+        return { runtime: "auto", status: "ready", checks: [] };
+    return await hostRegistryClient.probeHost({
+        hostRuntime: runtime,
+        entryMode: "current-session",
+        projectRoot,
+        homeDir,
+        availableFunctions: [PLAIN_TEXT_INPUT],
+    });
+}
+//# sourceMappingURL=host-registry-client.mjs.map

package/dist/lib/host-registry-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-registry-client.mjs","sourceRoot":"","sources":["../../src/lib/host-registry-client.mts"],"names":[],"mappings":"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"}

package/dist/lib/install-assets.d.mts

@@ -0,0 +1,8 @@
+export declare const INSTALLED_TREES: {
+    from: string;
+    to: string[];
+}[];
+export declare const INSTALLED_FILES: string[];
+export declare const SKILLS_MANIFEST_REL = "installed-skills.json";
+export declare const AGENTS_MANIFEST_REL = "installed-agents.json";
+export declare const LEGACY_TRANSPORT_AGENT_NAMES: readonly string[];

package/{src → dist}/lib/install-assets.mjs

@@ -7,40 +7,37 @@
 //
 // Skills and agents are NOT here: they install outside ~/.okstra (host skill
 // homes, ~/.claude/agents) and are tracked per-target by their own manifests.
-
 // runtime/<from> is mirrored to ~/.okstra/<to...>. Mirrored, not merged: a file
 // the payload no longer ships is removed from the install, because Python
 // imports whatever is on disk and a stale module outlives the release that
 // dropped it.
 export const INSTALLED_TREES = [
-  { from: "python", to: ["lib", "python"] },
-  { from: "bin", to: ["bin"] },
-  { from: "templates", to: ["templates"] },
-  { from: "schemas", to: ["schemas"] },
-  { from: "validators", to: ["lib", "validators"] },
-  { from: "prompts", to: ["prompts"] },
+    { from: "python", to: ["lib", "python"] },
+    { from: "bin", to: ["bin"] },
+    { from: "templates", to: ["templates"] },
+    { from: "schemas", to: ["schemas"] },
+    { from: "validators", to: ["lib", "validators"] },
+    { from: "prompts", to: ["prompts"] },
 ];
-
 // Single files the install stamps into ~/.okstra. Every one is removed by
 // uninstall; `installed-from` is written by no current code path and is listed
 // so that homes carrying it from an older version still get cleaned.
 export const INSTALLED_FILES = [
-  "version",
-  "dev-link",
-  "installed-from",
-  "installed-skills.json",
-  "installed-agents.json",
-  "installed-runtimes.json",
+    "version",
+    "dev-link",
+    "installed-from",
+    "installed-skills.json",
+    "installed-agents.json",
+    "installed-runtimes.json",
 ];
-
 export const SKILLS_MANIFEST_REL = "installed-skills.json";
 export const AGENTS_MANIFEST_REL = "installed-agents.json";
-
 // Exact names of the retired LLM transport wrappers. Install removes an entry
 // only when the previous agent manifest proves that Okstra installed it.
 export const LEGACY_TRANSPORT_AGENT_NAMES = Object.freeze([
-  "codex-worker.md",
-  "antigravity-worker.md",
-  "grok-worker.md",
-  "kimi-worker.md",
+    "codex-worker.md",
+    "antigravity-worker.md",
+    "grok-worker.md",
+    "kimi-worker.md",
 ]);
+//# sourceMappingURL=install-assets.mjs.map

package/dist/lib/install-assets.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-assets.mjs","sourceRoot":"","sources":["../../src/lib/install-assets.mts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,iCAAiC;AACjC,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAE9E,gFAAgF;AAChF,0EAA0E;AAC1E,2EAA2E;AAC3E,cAAc;AACd,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE;IACzC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE;IAC5B,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,EAAE;IACxC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE;IACpC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE;IACjD,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE;CACrC,CAAC;AAEF,0EAA0E;AAC1E,+EAA+E;AAC/E,qEAAqE;AACrE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS;IACT,UAAU;IACV,gBAAgB;IAChB,uBAAuB;IACvB,uBAAuB;IACvB,yBAAyB;CAC1B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D,8EAA8E;AAC9E,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CAAC;IACxD,iBAAiB;IACjB,uBAAuB;IACvB,gBAAgB;IAChB,gBAAgB;CACjB,CAAC,CAAC"}

package/dist/lib/okstra-dirs.d.mts

@@ -0,0 +1,4 @@
+export declare const OKSTRA_DIR = ".okstra";
+export declare const LEGACY_OKSTRA_DIR = "./okstra";
+export declare function okstraRoot(projectRoot: string): string;
+export declare function projectJsonPath(projectRoot: string): string;

package/{src → dist}/lib/okstra-dirs.mjs

@@ -8,19 +8,16 @@
 //
 // 의존성은 `node:path` 만 — `src/install.mjs` / `src/setup.mjs` 등 무거운
 // 모듈에서 import 할 때 순환 위험을 피한다.
-
 import { join } from "node:path";
-
 export const OKSTRA_DIR = ".okstra";
 // Pre-v0.37 layout. `okstra migrate` reads this to find unmigrated projects.
 // 코드 path 빌드에는 절대 사용 금지 — `OKSTRA_DIR` 만. 오로지 migration
 // 탐지/안내 메시지 용도.
 export const LEGACY_OKSTRA_DIR = "./okstra";
-
 export function okstraRoot(projectRoot) {
-  return join(projectRoot, OKSTRA_DIR);
+    return join(projectRoot, OKSTRA_DIR);
 }
-
 export function projectJsonPath(projectRoot) {
-  return join(okstraRoot(projectRoot), "project.json");
+    return join(okstraRoot(projectRoot), "project.json");
 }
+//# sourceMappingURL=okstra-dirs.mjs.map

package/dist/lib/okstra-dirs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"okstra-dirs.mjs","sourceRoot":"","sources":["../../src/lib/okstra-dirs.mts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,gEAAgE;AAChE,iDAAiD;AACjD,8DAA8D;AAC9D,8CAA8C;AAC9C,wCAAwC;AACxC,EAAE;AACF,iEAAiE;AACjE,8BAA8B;AAE9B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,6EAA6E;AAC7E,wDAAwD;AACxD,gBAAgB;AAChB,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE5C,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,OAAO,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC,CAAC;AACvD,CAAC"}

package/dist/lib/paths.d.mts

@@ -0,0 +1,4 @@
+import type { RuntimePaths } from "./types.mjs";
+export declare function resolveOkstraHome(): string;
+export declare function resolvePaths(): Promise<RuntimePaths>;
+export declare function buildPythonpath(paths: RuntimePaths): string;

package/dist/lib/paths.mjs

@@ -0,0 +1,78 @@
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { getPackageRoot, getPackageVersion } from "./version.mjs";
+function isStaleTmpHome(p) {
+    // tests/conftest.py creates the isolated home as `<tmp_path>/.okstra-isolated`
+    // under the system temp dir. Only a deleted one (env leaked, dir gone) heals;
+    // a soon-to-be-created `.okstra` temp home or a custom home is left untouched.
+    if (!p.endsWith("/.okstra-isolated"))
+        return false;
+    const roots = [tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+    return roots.some((r) => r && (p === r || p.startsWith(r.replace(/\/+$/, "") + "/")));
+}
+// Resolve OKSTRA_HOME, healing a leaked value: when it points at a missing
+// system-temp path (e.g. a deleted pytest-isolated home), warn and fall back
+// to ~/.okstra instead of operating on the dead directory.
+export function resolveOkstraHome() {
+    const raw = process.env.OKSTRA_HOME?.trim();
+    if (!raw)
+        return join(homedir(), ".okstra");
+    if (!existsSync(raw) && isStaleTmpHome(raw)) {
+        process.stderr.write(`⚠ OKSTRA_HOME=${raw} points to a missing temp dir (leaked test value); falling back to ~/.okstra\n`);
+        return join(homedir(), ".okstra");
+    }
+    return raw;
+}
+export async function resolvePaths() {
+    const home = resolveOkstraHome();
+    const pkgRoot = getPackageRoot();
+    const devLink = await readSimpleFile(join(home, "dev-link"));
+    const runtimeRoot = devLink || join(pkgRoot, "runtime");
+    return {
+        agents: join(runtimeRoot, "agents"),
+        workspace: runtimeRoot,
+        pythonpath: join(home, "lib", "python"),
+        bin: join(home, "bin"),
+        home,
+        package: await getPackageVersion(),
+        version: await readSimpleFile(join(home, "version")),
+        "dev-link": devLink || "",
+    };
+}
+function workspacePythonpath(paths) {
+    const candidates = [
+        join(paths.workspace, "python"),
+        join(paths.workspace, "scripts"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) || "";
+}
+// Compose the PYTHONPATH spawned python3 subprocesses should see.
+//
+// Precedence (first wins):
+//   1. process.env.PYTHONPATH (user override — e.g. in-repo `PYTHONPATH=scripts`
+//      for dev work without re-running `okstra install`).
+//   2. The package/dev-link workspace runtime selected by `okstra paths`.
+//   3. The installed user-runtime path (~/.okstra/lib/python).
+//
+// This is a colon-joined string suitable for direct assignment into the child
+// process env. Empty segments are dropped so a missing env var does not produce
+// a leading ':' (which Python treats as 'current directory').
+export function buildPythonpath(paths) {
+    const fragments = [
+        process.env.PYTHONPATH,
+        workspacePythonpath(paths),
+        paths.pythonpath,
+    ].filter((s) => typeof s === "string" && s.length > 0);
+    return fragments.join(":");
+}
+async function readSimpleFile(path) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=paths.mjs.map

package/dist/lib/paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.mjs","sourceRoot":"","sources":["../../src/lib/paths.mts"],"names":[],"mappings":"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"}

package/dist/lib/proc.d.mts

@@ -0,0 +1,3 @@
+import type { CliArgs, ProcessResult } from "./types.mjs";
+export declare function fileExists(p: string): Promise<boolean>;
+export declare function runProcess(cmd: string, args: CliArgs, env?: Readonly<Record<string, string | undefined>>): Promise<ProcessResult>;

package/dist/lib/proc.mjs

@@ -0,0 +1,31 @@
+// Shared filesystem / subprocess helpers used by the Node command modules.
+// Extracted to one place so a fix lands once instead of in each command file.
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+export async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Run `cmd args`, capturing stdout/stderr. `env` holds *additional* vars that
+// are merged over the inherited process.env. Never rejects — failures resolve
+// with { code: -1, stderr: <message> }.
+export function runProcess(cmd, args, env = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, ...env },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (b) => (stdout += b.toString()));
+        child.stderr.on("data", (b) => (stderr += b.toString()));
+        child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+        child.on("close", (code) => resolve({ code: typeof code === "number" ? code : 1, stdout, stderr }));
+    });
+}
+//# sourceMappingURL=proc.mjs.map

package/dist/lib/proc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"proc.mjs","sourceRoot":"","sources":["../../src/lib/proc.mts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAGzC,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,CAAS;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,8EAA8E;AAC9E,wCAAwC;AACxC,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,IAAa,EACb,GAAG,GAAiD,EAAE;IAEtD,OAAO,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,EAAE;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC7B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;YACjC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE;SAChC,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACzD,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACzD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC/E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACtG,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/python-helper.d.mts

@@ -0,0 +1,8 @@
+import type { InstalledScriptOptions, InstalledValidatorOptions, JsonErrorOptions, ProcessResult, PythonModuleOptions, PythonSnippetOptions, RuntimePaths } from "./types.mjs";
+export declare function resolveInstalledScript(paths: RuntimePaths, scriptName: string): string | null;
+export declare function resolveInstalledValidator(paths: RuntimePaths, validatorName: string): string | null;
+export declare function runInstalledScript({ scriptName, args, usage, emptyArgsCode }: InstalledScriptOptions): Promise<number>;
+export declare function runInstalledValidator({ validatorName, args }: InstalledValidatorOptions): Promise<number>;
+export declare function runPythonSnippet({ script, args, extraEnv }: PythonSnippetOptions): Promise<ProcessResult>;
+export declare function runPythonModule({ module, args, extraEnv, stdio }: PythonModuleOptions): Promise<ProcessResult>;
+export declare function emitJsonError({ stage, reason, extra }: JsonErrorOptions): void;

package/dist/lib/python-helper.mjs

@@ -0,0 +1,123 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildPythonpath, resolvePaths } from "./paths.mjs";
+export function resolveInstalledScript(paths, scriptName) {
+    // Prefer the installed copy under ~/.okstra/bin (what production users run);
+    // fall back to the in-repo source when invoked from a checkout that has not
+    // been installed (dev / CI).
+    const installed = join(paths.bin, scriptName);
+    if (existsSync(installed))
+        return installed;
+    const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
+    const dev = resolvePath(repoRoot, "scripts", scriptName);
+    return existsSync(dev) ? dev : null;
+}
+export function resolveInstalledValidator(paths, validatorName) {
+    // `okstra install` lands the validators tree at ~/.okstra/lib/validators;
+    // a checkout that has not been installed still has the in-repo source.
+    const installed = join(paths.home, "lib", "validators", validatorName);
+    if (existsSync(installed))
+        return installed;
+    const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
+    const dev = resolvePath(repoRoot, "validators", validatorName);
+    return existsSync(dev) ? dev : null;
+}
+async function spawnPythonEntry(entry, args, paths) {
+    return await new Promise((resolve) => {
+        const child = spawn("python3", [entry, ...args], {
+            stdio: "inherit",
+            env: { ...process.env, PYTHONPATH: buildPythonpath(paths) },
+        });
+        child.on("error", (err) => {
+            process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
+            resolve(1);
+        });
+        child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
+    });
+}
+// Thin spawn shim shared by every `okstra <cmd>` subcommand that fronts a
+// `scripts/okstra-*.py` entry point. Centralizing it keeps PYTHONPATH wiring
+// and installed/dev resolution in one place so skills call `okstra <cmd>`
+// instead of emitting `python3 "$HOME/..."` (which breaks `Bash(okstra:*)`
+// permission matching and prompts on every call).
+export async function runInstalledScript({ scriptName, args, usage, emptyArgsCode = 2 }) {
+    if (args.length === 0) {
+        process.stdout.write(usage);
+        return emptyArgsCode;
+    }
+    // Only a bare `--help` / `-h` prints the wrapper usage. A `--help` that
+    // follows a subcommand (e.g. `error-log append-observed --help`) must reach
+    // the python helper so its own per-subcommand help shows through.
+    if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const paths = await resolvePaths();
+    const entry = resolveInstalledScript(paths, scriptName);
+    if (!entry) {
+        process.stderr.write(`error: ${scriptName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`);
+        return 1;
+    }
+    return await spawnPythonEntry(entry, args, paths);
+}
+export async function runInstalledValidator({ validatorName, args }) {
+    const paths = await resolvePaths();
+    const entry = resolveInstalledValidator(paths, validatorName);
+    if (!entry) {
+        process.stderr.write(`error: ${validatorName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`);
+        return 1;
+    }
+    return await spawnPythonEntry(entry, args, paths);
+}
+export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
+    const paths = await resolvePaths();
+    return new Promise((resolve) => {
+        const child = spawn("python3", ["-c", script, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
+        });
+        // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
+        // large rendered prompts some capture-mode callers stream through here.
+        const outChunks = [];
+        const errChunks = [];
+        child.stdout?.on("data", (b) => outChunks.push(b));
+        child.stderr?.on("data", (b) => errChunks.push(b));
+        child.on("error", (err) => resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }));
+        child.on("close", (code) => resolve({
+            code: typeof code === "number" ? code : 1,
+            stdout: Buffer.concat(outChunks).toString(),
+            stderr: Buffer.concat(errChunks).toString(),
+        }));
+    });
+}
+export async function runPythonModule({ module, args = [], extraEnv = {}, stdio = "inherit-stdout" }) {
+    const paths = await resolvePaths();
+    return new Promise((resolve) => {
+        const child = spawn("python3", ["-m", module, ...args], {
+            stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
+            env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
+        });
+        // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
+        // large rendered prompts some capture-mode callers stream through here.
+        const outChunks = [];
+        const errChunks = [];
+        if (stdio === "capture") {
+            child.stdout?.on("data", (b) => outChunks.push(b));
+            child.stderr?.on("data", (b) => errChunks.push(b));
+        }
+        child.on("error", (err) => resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }));
+        // A signal-killed child reports code === null; normalize to a non-zero exit
+        // here so every consumer inherits correct failure semantics from one place.
+        child.on("close", (code) => resolve({
+            code: typeof code === "number" ? code : 1,
+            stdout: Buffer.concat(outChunks).toString(),
+            stderr: Buffer.concat(errChunks).toString(),
+        }));
+    });
+}
+export function emitJsonError({ stage, reason, extra = {} }) {
+    process.stdout.write(JSON.stringify({ ok: false, stage, reason, ...extra }, null, 2) + "\n");
+}
+//# sourceMappingURL=python-helper.mjs.map