aiwcli 0.15.5 → 0.17.0

package/dist/lib/runtime/cli-args.js

@@ -0,0 +1,200 @@
+/**
+ * Centralized CLI argument construction for agent subprocesses.
+ * Single source of truth for Claude CLI and Codex CLI flag patterns,
+ * platform quoting, model tier resolution, and env setup.
+ */
+import { CLAUDE_MODELS, CODEX_MODELS, DEVIN_MODELS } from "./models.js";
+import { getInternalSubprocessEnv, shellQuoteWin } from "./subprocess-utils.js";
+const VALID_SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
+export function isCodexSandbox(value) {
+    return VALID_SANDBOXES.includes(value);
+}
+// ---------------------------------------------------------------------------
+// Model Tier Resolution
+// ---------------------------------------------------------------------------
+export const MODEL_TIERS = {
+    fast: CLAUDE_MODELS.haiku,
+    standard: CLAUDE_MODELS.sonnet,
+    smart: CLAUDE_MODELS.opus,
+};
+export const CODEX_MODEL_TIERS = {
+    fast: CODEX_MODELS.spark,
+    standard: CODEX_MODELS.codex,
+    smart: CODEX_MODELS.codex,
+};
+export const DEVIN_MODEL_TIERS = {
+    fast: DEVIN_MODELS.sonnet,
+    standard: DEVIN_MODELS.swe,
+    smart: DEVIN_MODELS.opus,
+};
+export const TIER_TIMEOUTS = {
+    fast: 15,
+    standard: 30,
+    smart: 90,
+};
+export function isModelTier(value) {
+    return value in MODEL_TIERS;
+}
+export function resolveModel(model) {
+    if (isModelTier(model))
+        return MODEL_TIERS[model];
+    return model;
+}
+export function resolveModelForProvider(model, provider) {
+    if (!isModelTier(model))
+        return model;
+    if (provider === "codex")
+        return CODEX_MODEL_TIERS[model];
+    if (provider === "devin")
+        return DEVIN_MODEL_TIERS[model];
+    return MODEL_TIERS[model];
+}
+export function getTierTimeout(tier) {
+    return TIER_TIMEOUTS[tier];
+}
+/** Resolve a Codex model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export function resolveCodexModel(input) {
+    if (isModelTier(input))
+        return CODEX_MODEL_TIERS[input];
+    return input;
+}
+/** Resolve a Devin model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export function resolveDevinModel(input) {
+    if (isModelTier(input))
+        return DEVIN_MODEL_TIERS[input];
+    return input;
+}
+// ---------------------------------------------------------------------------
+// Core Builder
+// ---------------------------------------------------------------------------
+export function buildCliInvocation(spec) {
+    const env = getInternalSubprocessEnv();
+    delete env.ANTHROPIC_API_KEY;
+    if (spec.mode === "repl") {
+        const resolvedModel = spec.model ? resolveModelForProvider(spec.model, spec.provider) : undefined;
+        return buildCodexReplInvocation(spec, resolvedModel, env);
+    }
+    const resolvedModel = resolveModelForProvider(spec.model, spec.provider);
+    const isWin = process.platform === "win32";
+    const empty = isWin ? '""' : "";
+    if (spec.provider === "claude") {
+        return buildClaudeInvocation(spec, resolvedModel, isWin, empty, env);
+    }
+    return buildCodexInvocation(spec, resolvedModel, env);
+}
+function buildClaudeInvocation(spec, model, isWin, empty, env) {
+    const args = [];
+    args.push("--model", model);
+    if (spec.mode === "print") {
+        args.push("--print");
+    }
+    else {
+        // structured and preflight both use json output
+        args.push("--output-format", "json");
+        if (spec.jsonSchema) {
+            args.push("--json-schema", shellQuoteWin(JSON.stringify(spec.jsonSchema)));
+        }
+        const maxTurns = spec.mode === "preflight" ? 1 : (spec.maxTurns ?? 3);
+        args.push("--max-turns", String(maxTurns));
+    }
+    args.push("--setting-sources", empty);
+    args.push("-p");
+    args.push("--no-session-persistence");
+    if (spec.systemPrompt) {
+        args.push("--system-prompt", shellQuoteWin(spec.systemPrompt));
+    }
+    if (spec.extraArgs) {
+        args.push(...spec.extraArgs);
+    }
+    return { cliName: "claude", args, needsShell: isWin, env };
+}
+function buildCodexInvocation(spec, model, env) {
+    const args = ["exec"];
+    if (spec.sandbox) {
+        args.push("--sandbox", spec.sandbox);
+    }
+    args.push("--model", model);
+    if (spec.outputSchemaPath) {
+        args.push("--output-schema", spec.outputSchemaPath);
+    }
+    if (spec.outputFilePath) {
+        args.push("-o", spec.outputFilePath);
+    }
+    args.push("-");
+    if (spec.extraArgs) {
+        args.push(...spec.extraArgs);
+    }
+    return { cliName: "codex", args, needsShell: false, env };
+}
+function buildCodexReplInvocation(spec, model, env) {
+    const args = [];
+    if (spec.yolo)
+        args.push("--dangerously-bypass-approvals-and-sandbox");
+    if (spec.sandbox)
+        args.push("--sandbox", spec.sandbox);
+    if (model)
+        args.push("--model", model);
+    if (spec.extraArgs)
+        args.push(...spec.extraArgs);
+    return { cliName: "codex", args, needsShell: false, env };
+}
+// ---------------------------------------------------------------------------
+// Convenience Presets
+// ---------------------------------------------------------------------------
+export function preflightSpec(provider, model) {
+    if (provider === "codex") {
+        return {
+            provider: "codex",
+            model,
+            mode: "preflight",
+            sandbox: "read-only",
+        };
+    }
+    return {
+        provider: "claude",
+        model,
+        mode: "preflight",
+    };
+}
+export function inferenceSpec(model) {
+    return {
+        provider: "claude",
+        model,
+        mode: "print",
+    };
+}
+export function reviewSpec(provider, model, schema, systemPrompt) {
+    if (provider === "codex") {
+        return {
+            provider: "codex",
+            model,
+            mode: "structured",
+            sandbox: "read-only",
+        };
+    }
+    return {
+        provider: "claude",
+        model,
+        mode: "structured",
+        jsonSchema: schema,
+        ...(systemPrompt ? { systemPrompt } : {}),
+    };
+}
+export function codexReplSpec(model, sandbox, yolo) {
+    return {
+        provider: "codex",
+        mode: "repl",
+        ...(model ? { model } : {}),
+        ...(sandbox ? { sandbox } : {}),
+        ...(yolo !== undefined ? { yolo } : {}),
+    };
+}
+export function preflightCommandConfig(provider) {
+    const input = "Respond with exactly: ok";
+    return {
+        cliName: provider === "claude" ? "claude" : "codex",
+        buildArgs: (model) => buildCliInvocation(preflightSpec(provider, model)).args,
+        input,
+    };
+}
+export { CLAUDE_MODELS, CODEX_MODELS, DEVIN_MODELS } from "./models.js";

package/dist/lib/runtime/constants.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Constants and path utilities for shared context management.
+ * See SPEC.md §2
+ */
+export declare const MAX_CONTEXT_ID_LENGTH = 64;
+export declare const VALID_CONTEXT_ID_PATTERN: RegExp;
+export declare const MAX_EVENT_SIZE: number;
+export declare const MAX_INDEX_SIZE: number;
+export declare const MAX_RETRY_ATTEMPTS = 2;
+export declare const RETRY_BACKOFF_MS: number[];
+/**
+ * Sanitize a string into a valid context ID.
+ * See SPEC.md §2.3
+ */
+export declare function sanitizeContextId(contextId: string): string;
+/**
+ * Validate and normalize context ID.
+ * Throws only for security violations (path traversal).
+ * See SPEC.md §2.3
+ */
+export declare function validateContextId(contextId: string): string;
+/**
+ * Get project root from environment or cwd.
+ * Priority: CLAUDE_PROJECT_DIR > walk up from payload cwd > walk up from process.cwd()
+ * Walks upward to find the nearest .aiwcli/ anchor, so cwd drift (e.g. after
+ * `cd packages/cli` in a Bash tool call) doesn't break hook resolution.
+ * See SPEC.md §2.2
+ */
+export declare function getProjectRoot(payloadCwd?: string): string;
+export declare function getAiwcliDir(projectRoot?: string): string;
+export declare function getOutputDir(projectRoot?: string): string;
+export declare function getContextsDir(projectRoot?: string): string;
+export declare function getContextDir(contextId: string, projectRoot?: string): string;
+export declare function getContextPlansDir(contextId: string, projectRoot?: string): string;
+export declare function getContextHandoffsDir(contextId: string, projectRoot?: string): string;
+export declare function getContextReviewsDir(contextId: string, projectRoot?: string): string;
+export declare function getIndexPath(projectRoot?: string): string;
+export declare function getContextFilePath(contextId: string, projectRoot?: string): string;
+export declare function getEventsFilePath(contextId: string, projectRoot?: string): string;
+export declare function getAutoStatePath(contextId: string, projectRoot?: string): string;
+export declare function getArchiveDir(projectRoot?: string): string;
+export declare function getArchiveContextDir(contextId: string, projectRoot?: string): string;
+export declare function getArchiveIndexPath(projectRoot?: string): string;
+/**
+ * Get path for a new handoff folder with datetime naming.
+ * Handles collisions by appending -N suffix.
+ * See SPEC.md §2.4
+ */
+export declare function getHandoffFolderPath(contextId: string, projectRoot?: string): string;
+/**
+ * Get path for a new review folder.
+ * See SPEC.md §2.4
+ */
+export declare function getReviewFolderPath(contextId: string, iteration: number, projectRoot?: string): string;
+export declare function sanitizeFilename(s: string, maxLen?: number, allowLeadingDot?: boolean): string;
+export declare function sanitizeTitle(s: string, maxLen?: number): string;

package/dist/lib/runtime/constants.js

@@ -0,0 +1,230 @@
+/**
+ * Constants and path utilities for shared context management.
+ * See SPEC.md §2
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { logWarn } from "./logger.js";
+// Directory names (relative to project root)
+const OUTPUT_DIR = "_output";
+const CONTEXTS_DIR = "contexts";
+const ARCHIVE_DIR = "_archive";
+const INDEX_FILENAME = "index.json";
+// Context ID validation
+export const MAX_CONTEXT_ID_LENGTH = 64;
+export const VALID_CONTEXT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$/;
+// File size limits
+export const MAX_EVENT_SIZE = 64 * 1024;
+export const MAX_INDEX_SIZE = 1024 * 1024;
+// Performance constants
+export const MAX_RETRY_ATTEMPTS = 2;
+export const RETRY_BACKOFF_MS = [500, 1000];
+// Windows reserved filenames
+const WINDOWS_RESERVED = new Set([
+    "AUX", "COM1", "COM2", "COM3",
+    "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "CON", "LPT1", "LPT2",
+    "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", "NUL", "PRN",
+]);
+/**
+ * Sanitize a string into a valid context ID.
+ * See SPEC.md §2.3
+ */
+export function sanitizeContextId(contextId) {
+    if (!contextId)
+        return "context";
+    let result = contextId.toLowerCase();
+    result = result.replaceAll(/[^a-z0-9_-]/g, "-");
+    result = result.replaceAll(/[-_]+/g, "-");
+    result = result.replaceAll(/^[-_]+|[-_]+$/g, "");
+    if (result.length > MAX_CONTEXT_ID_LENGTH) {
+        result = result.slice(0, MAX_CONTEXT_ID_LENGTH).replace(/[-_]+$/, "");
+    }
+    return result || "context";
+}
+/**
+ * Validate and normalize context ID.
+ * Throws only for security violations (path traversal).
+ * See SPEC.md §2.3
+ */
+export function validateContextId(contextId) {
+    if (!contextId)
+        return "context";
+    // SECURITY: Check for path traversal BEFORE unknown normalization
+    if (contextId.includes("..") ||
+        contextId.includes("/") ||
+        contextId.includes("\\")) {
+        throw new Error(`Invalid context ID '${contextId}': path traversal not allowed`);
+    }
+    // Check for URL-encoded variants
+    const lower = contextId.toLowerCase();
+    if (lower.includes("%2e") ||
+        lower.includes("%2f") ||
+        lower.includes("%5c")) {
+        throw new Error(`Invalid context ID '${contextId}': encoded path traversal not allowed`);
+    }
+    return sanitizeContextId(contextId);
+}
+/**
+ * Walk up from startDir until a directory containing `.aiwcli/` is found.
+ * Returns startDir itself if no anchor is found (fail-safe).
+ * See SPEC.md §2.2
+ */
+function findProjectRoot(startDir) {
+    let dir = startDir;
+    while (true) {
+        if (fs.existsSync(path.join(dir, ".aiwcli")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root reached
+        dir = parent;
+    }
+    return startDir; // fallback: no .aiwcli anchor found
+}
+/**
+ * Get project root from environment or cwd.
+ * Priority: CLAUDE_PROJECT_DIR > walk up from payload cwd > walk up from process.cwd()
+ * Walks upward to find the nearest .aiwcli/ anchor, so cwd drift (e.g. after
+ * `cd packages/cli` in a Bash tool call) doesn't break hook resolution.
+ * See SPEC.md §2.2
+ */
+export function getProjectRoot(payloadCwd) {
+    const envDir = process.env.CLAUDE_PROJECT_DIR;
+    if (envDir) {
+        if (!path.isAbsolute(envDir)) {
+            logWarn("utils", `CLAUDE_PROJECT_DIR is not absolute: '${envDir}', ignoring`);
+        }
+        else if (envDir.includes("..")) {
+            logWarn("utils", `CLAUDE_PROJECT_DIR contains '..': '${envDir}', ignoring`);
+        }
+        else {
+            return envDir;
+        }
+    }
+    if (payloadCwd)
+        return findProjectRoot(payloadCwd);
+    return findProjectRoot(process.cwd());
+}
+// §2.4 — Path functions
+export function getAiwcliDir(projectRoot) {
+    return path.join(projectRoot ?? getProjectRoot(), ".aiwcli");
+}
+export function getOutputDir(projectRoot) {
+    return path.join(projectRoot ?? getProjectRoot(), OUTPUT_DIR);
+}
+export function getContextsDir(projectRoot) {
+    return path.join(getOutputDir(projectRoot), CONTEXTS_DIR);
+}
+export function getContextDir(contextId, projectRoot) {
+    const validatedId = validateContextId(contextId);
+    const contextsDir = getContextsDir(projectRoot);
+    const resultPath = path.join(contextsDir, validatedId);
+    // SECURITY: Verify resolved path stays within contexts directory
+    const resolved = path.resolve(resultPath);
+    const contextsResolved = path.resolve(contextsDir);
+    if (!resolved.toLowerCase().startsWith(contextsResolved.toLowerCase())) {
+        throw new Error(`Invalid context ID '${contextId}': path escapes contexts directory`);
+    }
+    return resultPath;
+}
+export function getContextPlansDir(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "plans");
+}
+export function getContextHandoffsDir(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "handoffs");
+}
+export function getContextReviewsDir(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "reviews");
+}
+export function getIndexPath(projectRoot) {
+    return path.join(getOutputDir(projectRoot), INDEX_FILENAME);
+}
+export function getContextFilePath(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "context.json");
+}
+export function getEventsFilePath(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "events.jsonl");
+}
+export function getAutoStatePath(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "auto-state.json");
+}
+export function getArchiveDir(projectRoot) {
+    return path.join(getContextsDir(projectRoot), ARCHIVE_DIR);
+}
+export function getArchiveContextDir(contextId, projectRoot) {
+    const validatedId = validateContextId(contextId);
+    return path.join(getArchiveDir(projectRoot), validatedId);
+}
+export function getArchiveIndexPath(projectRoot) {
+    return path.join(getArchiveDir(projectRoot), INDEX_FILENAME);
+}
+/**
+ * Get path for a new handoff folder with datetime naming.
+ * Handles collisions by appending -N suffix.
+ * See SPEC.md §2.4
+ */
+export function getHandoffFolderPath(contextId, projectRoot) {
+    const handoffsDir = getContextHandoffsDir(contextId, projectRoot);
+    const now = new Date();
+    const timestamp = [
+        now.getFullYear().toString(),
+        String(now.getMonth() + 1).padStart(2, "0"),
+        String(now.getDate()).padStart(2, "0"),
+        "-",
+        String(now.getHours()).padStart(2, "0"),
+        String(now.getMinutes()).padStart(2, "0"),
+    ].join("");
+    // Format: YYYY-MM-DD-HHMM
+    const ts = `${timestamp.slice(0, 4)}-${timestamp.slice(4, 6)}-${timestamp.slice(6, 8)}${timestamp.slice(8)}`;
+    let folder = path.join(handoffsDir, ts);
+    let counter = 1;
+    while (fs.existsSync(folder)) {
+        folder = path.join(handoffsDir, `${ts}-${counter}`);
+        counter++;
+    }
+    return folder;
+}
+/**
+ * Get path for a new review folder.
+ * See SPEC.md §2.4
+ */
+export function getReviewFolderPath(contextId, iteration, projectRoot) {
+    const reviewsDir = path.join(getContextReviewsDir(contextId, projectRoot), "cc-native");
+    const now = new Date();
+    const ts = [
+        now.getFullYear().toString(),
+        "-",
+        String(now.getMonth() + 1).padStart(2, "0"),
+        "-",
+        String(now.getDate()).padStart(2, "0"),
+        "-",
+        String(now.getHours()).padStart(2, "0"),
+        String(now.getMinutes()).padStart(2, "0"),
+    ].join("");
+    return path.join(reviewsDir, `${ts}-iteration-${iteration}`);
+}
+// §2.5 — Filename sanitization
+export function sanitizeFilename(s, maxLen = 32, allowLeadingDot = false) {
+    let result = s.replaceAll(/[^A-Za-z0-9._-]+/g, "_");
+    result = result.replaceAll(/^[._-]+|[._-]+$/g, "").slice(0, maxLen) || "unknown";
+    if (!allowLeadingDot) {
+        result = result.replace(/^\.+/, "");
+    }
+    const baseName = (result.split(".")[0] ?? result).toUpperCase();
+    if (WINDOWS_RESERVED.has(baseName)) {
+        result = `_${result}`;
+    }
+    return result || "unknown";
+}
+export function sanitizeTitle(s, maxLen = 50) {
+    let result = s.toLowerCase().trim();
+    result = result.replaceAll(' ', "-");
+    result = result.replaceAll(/[^a-z0-9._-]+/g, "_");
+    result = result.replaceAll(/[-_]+/g, "-");
+    result = result.replaceAll(/^[._-]+|[._-]+$/g, "").slice(0, maxLen) || "unknown";
+    const baseName = (result.split(".")[0] ?? result).toUpperCase();
+    if (WINDOWS_RESERVED.has(baseName)) {
+        result = `_${result}`;
+    }
+    return result || "unknown";
+}

package/dist/lib/runtime/executable-policy.d.ts

@@ -0,0 +1,16 @@
+export type WindowsLookupProfile = 'cmdOrExeFirst' | 'exeThenExtensionlessThenCmd';
+export declare function parseLookupLines(stdout: string): string[];
+export declare function pickWindowsPath(lines: string[], profile: WindowsLookupProfile): null | string;
+export declare function selectLookupPath(lines: string[], platform?: NodeJS.Platform, windowsProfile?: WindowsLookupProfile): null | string;
+export declare function resolveExecutable(name: string, options?: {
+    platform?: NodeJS.Platform | undefined;
+    timeoutMs?: number | undefined;
+    windowsHide?: boolean | undefined;
+    windowsProfile?: undefined | WindowsLookupProfile;
+}): null | string;
+export declare function isCommandAvailable(name: string, platform?: NodeJS.Platform): boolean;
+export declare function lookupExecutables(name: string, options?: {
+    platform?: NodeJS.Platform | undefined;
+    timeoutMs?: number | undefined;
+    windowsHide?: boolean | undefined;
+}): string[];

package/dist/lib/runtime/executable-policy.js

@@ -0,0 +1,57 @@
+import { execSync } from 'node:child_process';
+import { commandLookupBinary, isWindowsPlatform } from './platform-adapter.js';
+export function parseLookupLines(stdout) {
+    return stdout
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+export function pickWindowsPath(lines, profile) {
+    if (lines.length === 0)
+        return null;
+    if (profile === 'cmdOrExeFirst') {
+        return lines.find((line) => /\.(cmd|exe)$/i.test(line)) ?? lines[0] ?? null;
+    }
+    return lines.find((line) => /\.exe$/i.test(line))
+        ?? lines.find((line) => !/\.(cmd|ps1)$/i.test(line))
+        ?? lines.find((line) => /\.cmd$/i.test(line))
+        ?? lines[0]
+        ?? null;
+}
+export function selectLookupPath(lines, platform = process.platform, windowsProfile = 'cmdOrExeFirst') {
+    if (lines.length === 0)
+        return null;
+    if (!isWindowsPlatform(platform))
+        return lines[0] ?? null;
+    return pickWindowsPath(lines, windowsProfile);
+}
+export function resolveExecutable(name, options) {
+    const platform = options?.platform ?? process.platform;
+    const lines = lookupExecutables(name, {
+        platform,
+        timeoutMs: options?.timeoutMs,
+        windowsHide: options?.windowsHide,
+    });
+    return selectLookupPath(lines, platform, options?.windowsProfile ?? 'cmdOrExeFirst');
+}
+export function isCommandAvailable(name, platform = process.platform) {
+    return resolveExecutable(name, { platform }) !== null;
+}
+export function lookupExecutables(name, options) {
+    const platform = options?.platform ?? process.platform;
+    const lookupBin = commandLookupBinary(platform);
+    const cmd = `${lookupBin} ${name}`;
+    try {
+        return parseLookupLines(execSync(cmd, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            shell: true,
+            timeout: options?.timeoutMs ?? 3000,
+            windowsHide: options?.windowsHide ?? true,
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/runtime/git-state.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Capture current git state for session snapshots.
+ * All fields are optional — failures are silently ignored.
+ */
+export declare function getGitState(projectRoot: string): Record<string, unknown>;
+/**
+ * Get short git status string for display (e.g., in handoff documents).
+ */
+export declare function getGitStatusShort(projectRoot?: string): string;

package/dist/lib/runtime/git-state.js

@@ -0,0 +1,59 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Capture current git state for session snapshots.
+ * All fields are optional — failures are silently ignored.
+ */
+export function getGitState(projectRoot) {
+    const gitState = {};
+    const isWin = process.platform === "win32";
+    const opts = {
+        cwd: projectRoot,
+        timeout: 5000,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: isWin,
+    };
+    try {
+        const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], opts);
+        if (branch)
+            gitState.branch = branch.trim();
+    }
+    catch { /* non-fatal */ }
+    try {
+        const status = execFileSync("git", ["status", "--short"], opts);
+        if (status) {
+            const files = status.trim().split(/\r?\n/)
+                .filter(Boolean)
+                .slice(0, 10)
+                .map(line => line.trimStart().split(/\s+/).slice(1).join(" "));
+            if (files.length > 0)
+                gitState.uncommitted_files = files;
+        }
+    }
+    catch { /* non-fatal */ }
+    try {
+        const log = execFileSync("git", ["log", "-1", "--oneline"], opts);
+        if (log)
+            gitState.last_commit_short = log.trim();
+    }
+    catch { /* non-fatal */ }
+    return gitState;
+}
+/**
+ * Get short git status string for display (e.g., in handoff documents).
+ */
+export function getGitStatusShort(projectRoot) {
+    try {
+        const result = execFileSync("git", ["status", "--short"], {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+            ...(projectRoot ? { cwd: projectRoot } : {}),
+            shell: process.platform === "win32",
+        });
+        return result.trim() || "(no changes)";
+    }
+    catch {
+        return "(git status unavailable)";
+    }
+}

package/dist/lib/runtime/inference.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Inference utility for AI-powered text processing.
+ * Unified interface for Claude API calls using the claude CLI.
+ * See SPEC.md §6
+ */
+import type { InferenceResult } from "../types.js";
+/**
+ * Run inference using the claude CLI.
+ * See SPEC.md §6.1
+ */
+export declare function inference(systemPrompt: string, userPrompt: string, level?: string, timeout?: number, options?: {
+    model?: string;
+}): InferenceResult;
+/**
+ * Generate a keyword summary of a user prompt.
+ * Uses Sonnet (standard tier). Returns null if inference fails.
+ * See SPEC.md §6.2
+ */
+export declare function generateSemanticSummary(prompt: string, timeout?: number): string | null;
+/**
+ * Generate a 5-12 word context ID slug from a user prompt.
+ * Uses Codex Spark first, then falls back to current fast tier for resilience.
+ * See SPEC.md §6.3
+ */
+export declare function generateContextIdSlug(prompt: string, timeout?: number): string | null;
+/**
+ * Async version of inference() that does NOT block the event loop.
+ * Use for parallel AI calls (e.g., Stage 3 parallel summarizers).
+ * Uses execFileAsync and getInternalSubprocessEnv for proper subprocess isolation.
+ */
+export declare function inferenceAsync(systemPrompt: string, userPrompt: string, level?: string, timeout?: number, options?: {
+    model?: string;
+}): Promise<InferenceResult>;
+export declare function codexInferAsync(prompt: string, model: string, options?: {
+    sandbox?: string;
+    timeout?: number;
+}): Promise<InferenceResult>;