aiwcli 0.15.7 → 0.17.0

package/dist/lib/prompt-file-manager.js

@@ -0,0 +1,41 @@
+/**
+ * PromptFileManager — owns prompt file lifecycle (creation, cleanup).
+ * Replaces scattered writeFileSync calls for prompt temp files.
+ */
+import { writeFileSync } from 'node:fs';
+import * as fs from 'node:fs';
+import path from 'node:path';
+export class PromptFileManager {
+    files = [];
+    tempDir;
+    now;
+    pid;
+    constructor(options) {
+        this.tempDir = options.tempDir;
+        this.now = options.now;
+        this.pid = options.pid;
+    }
+    /**
+     * Write prompt text to a temp file and return the path.
+     */
+    materialize(promptText) {
+        const filePath = path.join(this.tempDir, `aiwcli-prompt-${this.now()}-${this.pid}.txt`);
+        writeFileSync(filePath, promptText, { encoding: 'utf8', mode: 0o600 });
+        this.files.push(filePath);
+        return filePath;
+    }
+    /**
+     * Clean up all created prompt files. Call in finally block.
+     */
+    cleanup() {
+        for (const filePath of this.files) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+        this.files.length = 0;
+    }
+}

package/dist/lib/runtime/agent-launcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared agent-launcher utilities used by Codex, Devin, and future agent skills.
+ * Extracted from codex skill to avoid duplication across agent launch scripts.
+ */
+import type { ContextState } from "../types.js";
+export declare const POLL_INTERVAL_MS = 2000;
+export declare const POLL_TIMEOUT_MS = 3000;
+export declare const WAIT_TIMEOUT_MS_DEFAULT = 14400000;
+type PaneBackend = "tmux" | "window" | "exec";
+export interface PaneWatchTarget {
+    backend?: PaneBackend;
+    paneId?: string;
+    sentinelPath?: string;
+}
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Print to stderr (shared by agent launch scripts).
+ */
+export declare function eprint(...args: unknown[]): void;
+/**
+ * Best-effort cleanup of a sentinel directory.
+ */
+export declare function cleanupSentinel(sentinelPath: string | null | undefined): void;
+/**
+ * Case-sensitive (or case-insensitive on Windows) path comparison.
+ */
+export declare function samePath(a: string, b: string): boolean;
+/**
+ * Heuristic check for LLM output that isn't a real summary.
+ */
+export declare function looksLikeBadSummary(output: string): boolean;
+/**
+ * Return a deterministic summary file path for a given agent prefix + task ID.
+ * Callers can advertise this path before the session finishes so consumers
+ * know where to look for the summary once it's written.
+ */
+export declare function getWellKnownSummaryPath(prefix: string, taskId: string, projectRoot?: string): string;
+export declare function persistSummary(summary: string, prefix: string, sessionId?: string, taskId?: string, projectRoot?: string): string | null;
+/** Fallback plan discovery: scan all context plan dirs by mtime. */
+export declare function findLatestPlanByMtime(projectRoot: string): string | null;
+export declare function buildFileModeBootstrapPrompt(targetPath: string, sourceLabel: "plan" | "file", extraPrompt?: string, orientation?: string): string;
+export declare function resolveContextForLaunch(contextFlag: string | undefined, projectRoot: string): ContextState | null;
+export interface WritePromptFileOpts {
+    ctx?: ContextState | null;
+    extraPrompt?: string;
+    projectRoot: string;
+    tempFilePrefix: string;
+}
+export interface WriteFileRefPromptFileOpts extends WritePromptFileOpts {
+    fileReferencePath: string;
+    label: "plan" | "file";
+}
+export interface WriteInlinePromptFileOpts extends WritePromptFileOpts {
+    text: string;
+}
+/**
+ * Build a file-reference bootstrap prompt and write it to a temp file.
+ * Returns the temp file path.
+ */
+export declare function writeFileRefPromptFile(opts: WriteFileRefPromptFileOpts): string;
+/**
+ * Write inline text to a temp file, prepend context orientation, append extra prompt.
+ * Returns the temp file path.
+ */
+export declare function writeInlinePromptFile(opts: WriteInlinePromptFileOpts): string;
+export declare function waitForPaneClose(target: string | PaneWatchTarget, timeoutMs?: number): Promise<void>;
+export {};

package/dist/lib/runtime/agent-launcher.js

@@ -0,0 +1,262 @@
+/**
+ * Shared agent-launcher utilities used by Codex, Devin, and future agent skills.
+ * Extracted from codex skill to avoid duplication across agent launch scripts.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import path from "node:path";
+import { logDebug, logWarn } from "./logger.js";
+import { execFileAsync, findExecutable } from "./subprocess-utils.js";
+import { buildExternalAgentContext } from "../context/context-formatter.js";
+import { getContextBySessionId, getContext } from "../context/context-store.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const POLL_INTERVAL_MS = 2000;
+export const POLL_TIMEOUT_MS = 3000;
+export const WAIT_TIMEOUT_MS_DEFAULT = 14_400_000;
+// ---------------------------------------------------------------------------
+// Generic Helpers
+// ---------------------------------------------------------------------------
+export function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Print to stderr (shared by agent launch scripts).
+ */
+export function eprint(...args) {
+    process.stderr.write(args.map(String).join(" ") + "\n");
+}
+/**
+ * Best-effort cleanup of a sentinel directory.
+ */
+export function cleanupSentinel(sentinelPath) {
+    if (!sentinelPath)
+        return;
+    try {
+        const dir = path.dirname(sentinelPath);
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Case-sensitive (or case-insensitive on Windows) path comparison.
+ */
+export function samePath(a, b) {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    if (process.platform === "win32") {
+        return left.toLowerCase() === right.toLowerCase();
+    }
+    return left === right;
+}
+/**
+ * Heuristic check for LLM output that isn't a real summary.
+ */
+export function looksLikeBadSummary(output) {
+    const normalized = output.toLowerCase();
+    return (normalized.includes("don't see") ||
+        normalized.includes("no output") ||
+        normalized.includes("could you provide") ||
+        normalized.includes("paste"));
+}
+/**
+ * Return a deterministic summary file path for a given agent prefix + task ID.
+ * Callers can advertise this path before the session finishes so consumers
+ * know where to look for the summary once it's written.
+ */
+export function getWellKnownSummaryPath(prefix, taskId, projectRoot) {
+    const sessionKey = projectRoot
+        ? path.basename(projectRoot)
+        : "unknown";
+    const dir = path.join(os.tmpdir(), "aiw-agent-output", sessionKey);
+    return path.join(dir, `${prefix}-${taskId}.md`).replaceAll("\\", "/");
+}
+export function persistSummary(summary, prefix, sessionId, taskId, projectRoot) {
+    try {
+        const suffix = sessionId
+            ? sessionId.replaceAll(/[^a-zA-Z0-9_-]/g, "").slice(0, 8)
+            : String(process.pid);
+        const filePath = path.join(os.tmpdir(), `${prefix}-summary-${Date.now()}-${suffix}.md`);
+        fs.writeFileSync(filePath, summary, "utf8");
+        // Also write to the well-known path for deterministic discovery.
+        if (taskId) {
+            try {
+                const wkPath = getWellKnownSummaryPath(prefix, taskId, projectRoot);
+                fs.mkdirSync(path.dirname(wkPath), { recursive: true });
+                fs.writeFileSync(wkPath, summary, "utf8");
+            }
+            catch {
+                logWarn("agent-launcher", "Failed to write well-known summary path");
+            }
+        }
+        return filePath.replaceAll("\\", "/");
+    }
+    catch (error) {
+        logWarn("agent-launcher", `Failed to persist summary: ${String(error)}`);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plan Discovery
+// ---------------------------------------------------------------------------
+/** Fallback plan discovery: scan all context plan dirs by mtime. */
+export function findLatestPlanByMtime(projectRoot) {
+    const contextsDir = path.join(projectRoot, "_output", "contexts");
+    if (!fs.existsSync(contextsDir))
+        return null;
+    let best = null;
+    for (const ctxEntry of fs.readdirSync(contextsDir)) {
+        if (ctxEntry.startsWith("_"))
+            continue;
+        const plansDir = path.join(contextsDir, ctxEntry, "plans");
+        if (!fs.existsSync(plansDir))
+            continue;
+        for (const file of fs.readdirSync(plansDir)) {
+            if (!file.endsWith(".md"))
+                continue;
+            const fullPath = path.join(plansDir, file);
+            try {
+                const mtime = fs.statSync(fullPath).mtimeMs;
+                if (!best || mtime > best.mtime) {
+                    best = { path: fullPath, mtime };
+                }
+            }
+            catch { /* skip unreadable */ }
+        }
+    }
+    return best?.path ?? null;
+}
+// ---------------------------------------------------------------------------
+// Bootstrap Prompt Construction
+// ---------------------------------------------------------------------------
+export function buildFileModeBootstrapPrompt(targetPath, sourceLabel, extraPrompt, orientation) {
+    const absolutePath = path.resolve(targetPath);
+    const sourceTitle = sourceLabel === "plan" ? "Plan Source" : "File Source";
+    const sections = ["## Startup Brief", ""];
+    if (orientation?.trim()) {
+        sections.push(orientation.trim(), "", "---", "");
+    }
+    sections.push(`## ${sourceTitle}`, "", `Primary input path: ${absolutePath}`, "", "Read this file directly from disk before taking action.", "Treat its contents as the source of truth.", "Do not ask for the file contents to be pasted inline.");
+    if (extraPrompt?.trim()) {
+        sections.push("", "## Additional Instructions", "", extraPrompt.trim());
+    }
+    return sections.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Context Resolution
+// ---------------------------------------------------------------------------
+export function resolveContextForLaunch(contextFlag, projectRoot) {
+    if (contextFlag) {
+        return getContext(contextFlag, projectRoot) ?? null;
+    }
+    const sessionId = process.env.CLAUDE_SESSION_ID;
+    if (sessionId) {
+        return getContextBySessionId(sessionId, projectRoot) ?? null;
+    }
+    return null;
+}
+/**
+ * Build a file-reference bootstrap prompt and write it to a temp file.
+ * Returns the temp file path.
+ */
+export function writeFileRefPromptFile(opts) {
+    let orientation = "";
+    if (opts.ctx) {
+        try {
+            orientation = buildExternalAgentContext(opts.ctx, opts.projectRoot);
+        }
+        catch {
+            logWarn("agent-launcher", `Context orientation build failed for ${opts.ctx.id}`);
+        }
+    }
+    const bootstrap = buildFileModeBootstrapPrompt(opts.fileReferencePath, opts.label, opts.extraPrompt, orientation);
+    const tempFile = path.join(os.tmpdir(), `${opts.tempFilePrefix}-file-ref-${Date.now()}.md`);
+    fs.writeFileSync(tempFile, bootstrap, "utf8");
+    return tempFile;
+}
+/**
+ * Write inline text to a temp file, prepend context orientation, append extra prompt.
+ * Returns the temp file path.
+ */
+export function writeInlinePromptFile(opts) {
+    let content = opts.text;
+    if (opts.ctx) {
+        try {
+            const orientation = buildExternalAgentContext(opts.ctx, opts.projectRoot);
+            content = `${orientation}\n\n---\n\n${content}`;
+        }
+        catch {
+            logWarn("agent-launcher", `Context orientation prepend failed for ${opts.ctx.id}`);
+        }
+    }
+    if (opts.extraPrompt?.trim()) {
+        content = `${content}\n\n---\n\n## Additional Instructions\n\n${opts.extraPrompt}`;
+    }
+    const tempFile = path.join(os.tmpdir(), `${opts.tempFilePrefix}-prompt-${Date.now()}.md`);
+    fs.writeFileSync(tempFile, content, "utf8");
+    return tempFile;
+}
+// ---------------------------------------------------------------------------
+// Pane Watching
+// ---------------------------------------------------------------------------
+async function waitForSentinelClose(sentinelPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (fs.existsSync(sentinelPath))
+            return;
+        if (Date.now() >= deadline) {
+            logDebug("agent-launcher", `watch timeout reached waiting for sentinel ${sentinelPath}`);
+            return;
+        }
+        const remainingMs = deadline - Date.now();
+        await sleep(Math.max(0, Math.min(POLL_INTERVAL_MS, remainingMs)));
+    }
+}
+function normalizeWatchTarget(target) {
+    if (typeof target === "string") {
+        return { backend: "tmux", paneId: target };
+    }
+    return target;
+}
+export async function waitForPaneClose(target, timeoutMs = WAIT_TIMEOUT_MS_DEFAULT) {
+    const watch = normalizeWatchTarget(target);
+    if (watch.sentinelPath) {
+        await waitForSentinelClose(watch.sentinelPath, timeoutMs);
+        return;
+    }
+    const backend = watch.backend ?? "tmux";
+    const paneId = watch.paneId ?? "";
+    if (backend !== "tmux") {
+        logDebug("agent-launcher", `No pane watcher for backend=${backend}; continuing without wait`);
+        return;
+    }
+    if (!paneId)
+        return;
+    const tmuxPath = findExecutable("tmux");
+    if (!tmuxPath) {
+        logWarn("agent-launcher", `tmux unavailable while watching pane ${paneId}`);
+        return;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (Date.now() >= deadline) {
+            logDebug("agent-launcher", `watch timeout reached for pane ${paneId} after ${timeoutMs}ms`);
+            return;
+        }
+        const result = await execFileAsync(tmuxPath, ["list-panes", "-a", "-F", "#{pane_id}"], {
+            timeout: POLL_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0) {
+            logDebug("agent-launcher", `list-panes failed; assuming pane closed (${result.stderr.trim() || "no stderr"})`);
+            return;
+        }
+        const activePaneIds = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (!activePaneIds.includes(paneId))
+            return;
+        const remainingMs = deadline - Date.now();
+        await sleep(Math.max(0, Math.min(POLL_INTERVAL_MS, remainingMs)));
+    }
+}

package/dist/lib/runtime/aiw-cli.d.ts

@@ -7,6 +7,8 @@
 export interface AiwLaunchOptions {
     /** Launch codex instead of claude. */
     codex?: boolean;
+    /** Launch devin instead of claude. */
+    devin?: boolean;
     /** Working directory. */
     cwd?: string;
     /** Extra env vars to inject. */

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

@@ -30,6 +30,8 @@ export async function aiwLaunch(options) {
     const args = ["launch"];
     if (options.codex)
         args.push("--codex");
+    if (options.devin)
+        args.push("--devin");
     if (options.wait)
         args.push("--wait");
     args.push("--json");
@@ -55,7 +57,7 @@ function parseJsonResult(result) {
         return {
             launched: Boolean(parsed.launched),
             backend: String(parsed.backend ?? "exec"),
-            paneId: parsed.paneId ?? null,
+            paneId: parsed.handle ?? parsed.paneId ?? null,
             sentinelPath: parsed.sentinelPath ?? null,
             exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : null,
             reason: parsed.reason ?? null,

package/dist/lib/runtime/cli-args.d.ts

@@ -5,7 +5,7 @@
  */
 import type { PreflightCommandConfig } from "./preflight.js";
 export type InvocationMode = "structured" | "print" | "preflight";
-export type CliProvider = "claude" | "codex";
+export type CliProvider = "claude" | "codex" | "devin";
 export type ModelTier = "fast" | "standard" | "smart";
 declare const VALID_SANDBOXES: readonly ["read-only", "workspace-write", "danger-full-access"];
 export type CodexSandbox = (typeof VALID_SANDBOXES)[number];
@@ -39,6 +39,7 @@ export interface CliInvocation {
 }
 export declare const MODEL_TIERS: Record<ModelTier, string>;
 export declare const CODEX_MODEL_TIERS: Record<ModelTier, string>;
+export declare const DEVIN_MODEL_TIERS: Record<ModelTier, string>;
 export declare const TIER_TIMEOUTS: Record<ModelTier, number>;
 export declare function isModelTier(value: string): value is ModelTier;
 export declare function resolveModel(model: string | ModelTier): string;
@@ -46,10 +47,12 @@ export declare function resolveModelForProvider(model: string | ModelTier, provi
 export declare function getTierTimeout(tier: ModelTier): number;
 /** Resolve a Codex model: tier resolution + pass-through. No aliases (those are skill-specific). */
 export declare function resolveCodexModel(input: string): string;
+/** Resolve a Devin model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export declare function resolveDevinModel(input: string): string;
 export declare function buildCliInvocation(spec: CliArgSpec | CodexReplSpec): CliInvocation;
 export declare function preflightSpec(provider: CliProvider, model: string): CliArgSpec;
 export declare function inferenceSpec(model: string | ModelTier): CliArgSpec;
 export declare function reviewSpec(provider: CliProvider, model: string, schema: Record<string, unknown>, systemPrompt?: string): CliArgSpec;
 export declare function codexReplSpec(model?: string, sandbox?: CodexSandbox, yolo?: boolean): CodexReplSpec;
 export declare function preflightCommandConfig(provider: CliProvider): PreflightCommandConfig;
-export { CLAUDE_MODELS, CODEX_MODELS } from "./models.js";
+export { CLAUDE_MODELS, CODEX_MODELS, DEVIN_MODELS } from "./models.js";

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

@@ -3,7 +3,7 @@
  * 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 } from "./models.js";
+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) {
@@ -22,6 +22,11 @@ export const CODEX_MODEL_TIERS = {
     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,
@@ -38,7 +43,11 @@ export function resolveModel(model) {
 export function resolveModelForProvider(model, provider) {
     if (!isModelTier(model))
         return model;
-    return provider === "codex" ? CODEX_MODEL_TIERS[model] : MODEL_TIERS[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];
@@ -49,6 +58,12 @@ export function resolveCodexModel(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
 // ---------------------------------------------------------------------------
@@ -182,4 +197,4 @@ export function preflightCommandConfig(provider) {
         input,
     };
 }
-export { CLAUDE_MODELS, CODEX_MODELS } from "./models.js";
+export { CLAUDE_MODELS, CODEX_MODELS, DEVIN_MODELS } from "./models.js";

package/dist/lib/runtime/inference.js

@@ -5,7 +5,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { logDebug, logWarn } from "./logger.js";
-import { STOP_WORDS } from "./stop-words.js";
+import { filterStopWords } from "./stop-words.js";
 import { buildCliInvocation, inferenceSpec, isModelTier, resolveModel, getTierTimeout, TIER_TIMEOUTS, } from "./cli-args.js";
 import { CODEX_MODELS } from "./models.js";
 import { execFileAsync } from "./subprocess-utils.js";
@@ -101,7 +101,7 @@ export function generateSemanticSummary(prompt, timeout = 15) {
     summary = summary.replaceAll(/^["']+|["']+$/g, "");
     summary = summary.replace(/[.!?]+$/, "");
     // Filter stop words
-    summary = filterStopWords(summary);
+    summary = filterStopWords(summary).toLowerCase();
     const words = summary.split(/\s+/);
     if (words.length < 6 || words.length > 12)
         return null;
@@ -146,7 +146,7 @@ Respond with ONLY a JSON object: {"slug": "your 8-12 word phrase here"}`;
  * Uses Codex Spark first, then falls back to current fast tier for resilience.
  * See SPEC.md §6.3
  */
-export function generateContextIdSlug(prompt, timeout = 3) {
+export function generateContextIdSlug(prompt, timeout = 8) {
     const truncated = prompt.slice(0, 500);
     const sparkResult = inference(CONTEXT_ID_SLUG_PROMPT, truncated, "fast", timeout, { model: CONTEXT_ID_PRIMARY_MODEL });
     if (!sparkResult.success || !sparkResult.output) {
@@ -249,14 +249,3 @@ export async function codexInferAsync(prompt, model, options) {
         latency_ms: latencyMs,
     };
 }
-/**
- * Filter stop words from text.
- * See SPEC.md §6.4
- */
-function filterStopWords(text) {
-    return text
-        .toLowerCase()
-        .split(/\s+/)
-        .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
-        .join(" ");
-}

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

@@ -12,3 +12,9 @@ export declare const CODEX_MODELS: {
     readonly codex: "gpt-5.4";
     readonly gpt: "gpt-5.4";
 };
+export declare const DEVIN_MODELS: {
+    readonly swe: "swe";
+    readonly gpt: "gpt";
+    readonly opus: "opus";
+    readonly sonnet: "sonnet";
+};

package/dist/lib/runtime/models.js

@@ -12,3 +12,9 @@ export const CODEX_MODELS = {
     codex: "gpt-5.4",
     gpt: "gpt-5.4",
 };
+export const DEVIN_MODELS = {
+    swe: "swe",
+    gpt: "gpt",
+    opus: "opus",
+    sonnet: "sonnet",
+};

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

@@ -6,7 +6,8 @@
 import type { ContextState } from "../types.js";
 /**
  * Serialize a ContextState for JSON output.
- * Omits null/undefined keys but keeps false, 0, empty string, and empty arrays.
+ * Omits undefined keys but preserves null (semantically meaningful in the schema).
+ * Keeps false, 0, empty string, and empty arrays.
  */
 export declare function toDict(state: ContextState): Record<string, unknown>;
 /**

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

@@ -8,6 +8,7 @@ import path from "node:path";
 import { atomicWrite } from "./atomic-write.js";
 import { getContextDir } from "./constants.js";
 import { logWarn } from "./logger.js";
+import { ContextStateSchema } from "../schemas.js";
 /** Mode migration from legacy context_manager values. */
 const MODE_MIGRATION = {
     none: "idle",
@@ -17,12 +18,13 @@ const MODE_MIGRATION = {
 };
 /**
  * Serialize a ContextState for JSON output.
- * Omits null/undefined keys but keeps false, 0, empty string, and empty arrays.
+ * Omits undefined keys but preserves null (semantically meaningful in the schema).
+ * Keeps false, 0, empty string, and empty arrays.
  */
 export function toDict(state) {
     const result = {};
     for (const [key, value] of Object.entries(state)) {
-        if (value !== null && value !== undefined) {
+        if (value !== undefined) {
             result[key] = value;
         }
     }
@@ -96,6 +98,11 @@ export function readStateJson(contextId, projectRoot) {
         const raw = fs.readFileSync(sp, "utf8");
         const data = JSON.parse(raw);
         migrateConsumedFlags(data); // Migrate before dictToState
+        const parsed = ContextStateSchema.safeParse(data);
+        if (!parsed.success) {
+            logWarn("state_io", `Schema validation failed for '${contextId}': ${parsed.error.message}`);
+            // Fail-open: still attempt to reconstruct state from raw data
+        }
         return dictToState(data);
     }
     catch (error) {
@@ -109,8 +116,6 @@ export function readStateJson(contextId, projectRoot) {
  */
 export function writeStateJson(contextId, state, projectRoot) {
     const sp = statePath(contextId, projectRoot);
-    const dir = path.dirname(sp);
-    fs.mkdirSync(dir, { recursive: true });
     const content = JSON.stringify(toDict(state), null, 2);
     // fsync: false — state.json is reconstructable from context folder contents
     return atomicWrite(sp, content, 2, [500, 1000], false);

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

@@ -52,3 +52,11 @@ export declare function generateSlug(text: string, maxLen?: number, fallbackSlug
  * See SPEC.md §14.2
  */
 export declare function generateContextId(summary: string, existingIds?: Set<string>): string;
+/**
+ * Get .md files in a directory sorted by mtime (newest first).
+ */
+export declare function getMdFilesByMtime(dir: string): string[];
+/**
+ * Get the most recently modified .md file in a directory.
+ */
+export declare function mostRecentMd(dir: string): string | null;

package/dist/lib/runtime/utils.js

@@ -2,6 +2,8 @@
  * Core utilities for shared context management.
  * See SPEC.md §14.2, §14.3
  */
+import * as fs from "node:fs";
+import path from "node:path";
 import { sanitizeTitle } from "./constants.js";
 import { logDebug, logError, logWarn } from "./logger.js";
 import { STOP_WORDS } from "./stop-words.js";
@@ -99,7 +101,7 @@ export function generateSlug(text, maxLen = 150, fallbackSlug = "context") {
     // Tier 1: AI inference via generateContextIdSlug (sync — uses execFileSync)
     try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports, no-undef
-        const { generateContextIdSlug } = require("./inference.js");
+        const { generateContextIdSlug } = require("./inference");
         const aiSlug = generateContextIdSlug(text);
         if (aiSlug) {
             const filteredWords = aiSlug
@@ -160,3 +162,31 @@ export function generateContextId(summary, existingIds) {
     }
     return `${baseId}-${counter}`;
 }
+/**
+ * Get .md files in a directory sorted by mtime (newest first).
+ */
+export function getMdFilesByMtime(dir) {
+    try {
+        if (!fs.existsSync(dir))
+            return [];
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        return entries
+            .filter(e => e.isFile() && e.name.endsWith(".md"))
+            .map(e => {
+            const fullPath = path.join(dir, e.name);
+            const stat = fs.statSync(fullPath);
+            return { path: fullPath, mtime: stat.mtimeMs };
+        })
+            .sort((a, b) => b.mtime - a.mtime)
+            .map(f => f.path);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the most recently modified .md file in a directory.
+ */
+export function mostRecentMd(dir) {
+    return getMdFilesByMtime(dir)[0] ?? null;
+}