aiwcli 0.15.4 → 0.15.7

package/dist/lib/runtime/logger.js

@@ -0,0 +1,201 @@
+/**
+ * Unified logging for all hooks and libraries.
+ *
+ * Log format: JSONL (one JSON object per line)
+ * Log location: _output/hook-log.jsonl (global, all sessions)
+ * Filter by session using the "sid" field.
+ *
+ * stderr is OPT-IN: convenience functions (logDebug, logInfo, logWarn, logError)
+ * write to file only by default. To also write to stderr (visible to Claude Code
+ * as "hook error"), pass { stderr: true } or use logBlocking().
+ * logHookError() always writes to stderr (unhandled errors must be visible).
+ *
+ * Environment variables:
+ * - HOOK_LOG_DISABLE=1: Disable all file logging
+ * - HOOK_LOG_LEVEL=warn: Minimum level to log (default: debug)
+ * - HOOK_ERROR_LOG_DISABLE=1: Legacy alias for HOOK_LOG_DISABLE
+ *
+ * Never throws. No buffering. Stdlib only.
+ * See SPEC.md §3
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+const LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const MAX_LOG_BYTES = 2_000_000; // 2MB threshold before pruning
+let _prunedThisProcess = false;
+// Module-level session ID cache
+let _cachedSessionId = null;
+// Module-level context path cache (kept for external callers)
+let _cachedContextPath = null;
+let _contextResolved = false;
+/**
+ * Set the session ID for this process. All subsequent log calls include it.
+ */
+export function setSessionId(sessionId) {
+    _cachedSessionId = sessionId;
+}
+/**
+ * Set the context path for this process. Kept for external callers.
+ */
+export function setContextPath(contextPath) {
+    _cachedContextPath = contextPath;
+    _contextResolved = true;
+}
+export function getContextPath() {
+    if (!_contextResolved) {
+        _contextResolved = true; // Don't retry
+    }
+    return _cachedContextPath;
+}
+function getMinLevel() {
+    const env = (process.env.HOOK_LOG_LEVEL ?? "debug").toLowerCase();
+    return LEVELS[env] ?? 0;
+}
+function isDisabled() {
+    return (process.env.HOOK_LOG_DISABLE === "1" ||
+        process.env.HOOK_ERROR_LOG_DISABLE === "1" ||
+        process.env.CCNATIVE_DEBUG_DISABLE === "1");
+}
+function getProjectRoot() {
+    return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+/**
+ * Write a structured log entry to the global hook log.
+ *
+ * All entries go to _output/hook-log.jsonl. Use the "sid" field
+ * (set via setSessionId) to filter by session.
+ */
+export function hookLog(level, hookName, message, opts) {
+    try {
+        const levelLower = level.toLowerCase();
+        const levelNum = LEVELS[levelLower] ?? 0;
+        const component = opts?.component ?? "";
+        const tracebackStr = opts?.traceback_str ?? "";
+        const stderrEnabled = opts?.stderr === true;
+        // Write to stderr
+        if (stderrEnabled) {
+            const prefix = component
+                ? `[${hookName}:${component}]`
+                : `[${hookName}]`;
+            process.stderr.write(`${prefix} ${message}\n`);
+            if (tracebackStr) {
+                process.stderr.write(tracebackStr + "\n");
+            }
+        }
+        // Check if file logging is enabled
+        if (isDisabled())
+            return;
+        // Check minimum level
+        if (levelNum < getMinLevel())
+            return;
+        // Build JSONL entry
+        const now = new Date();
+        const ts = now.toISOString().replace("Z", "").slice(0, 23);
+        const entry = {
+            ts,
+            level: levelLower,
+            hook: hookName,
+            msg: message,
+        };
+        if (_cachedSessionId)
+            entry.sid = _cachedSessionId;
+        if (component)
+            entry.component = component;
+        if (opts?.data !== undefined && opts.data !== null) {
+            try {
+                JSON.stringify(opts.data);
+                entry.data = opts.data;
+            }
+            catch {
+                entry.data = String(opts.data);
+            }
+        }
+        if (tracebackStr)
+            entry.tb = tracebackStr.trimEnd();
+        const line = JSON.stringify(entry) + "\n";
+        // Always write to global log
+        const logPath = path.join(getProjectRoot(), "_output", "hook-log.jsonl");
+        // Ensure directory exists
+        const dir = path.dirname(logPath);
+        fs.mkdirSync(dir, { recursive: true });
+        // Size-based prune: runs at most once per bun process
+        if (!_prunedThisProcess) {
+            _prunedThisProcess = true;
+            try {
+                const stat = fs.statSync(logPath);
+                if (stat.size > MAX_LOG_BYTES) {
+                    const content = fs.readFileSync(logPath, "utf8");
+                    const pruneTarget = Math.floor(content.length * 0.1);
+                    const keepFrom = content.indexOf("\n", pruneTarget);
+                    if (keepFrom > 0) {
+                        fs.writeFileSync(logPath, content.slice(keepFrom + 1), "utf8");
+                    }
+                }
+            }
+            catch { /* file doesn't exist yet — fine */ }
+        }
+        fs.appendFileSync(logPath, line, "utf8");
+    }
+    catch {
+        // Never crash
+    }
+}
+export function logDebug(hookName, message, opts) {
+    hookLog("debug", hookName, message, opts);
+}
+export function logInfo(hookName, message, opts) {
+    hookLog("info", hookName, message, opts);
+}
+export function logWarn(hookName, message, opts) {
+    hookLog("warn", hookName, message, opts);
+}
+export function logError(hookName, message, opts) {
+    hookLog("error", hookName, message, opts);
+}
+/**
+ * Log an error that SHOULD be visible to user/model via stderr.
+ * Use for real problems needing attention, not routine diagnostics.
+ */
+export function logBlocking(hookName, message, opts) {
+    hookLog("error", hookName, message, { ...opts, stderr: true });
+}
+/**
+ * Log a structured diagnostic entry at a hook decision point.
+ * See SPEC.md §3.8
+ */
+export function logDiagnostic(hookName, phase, summary, opts) {
+    const diagData = { phase };
+    if (opts?.inputs !== undefined)
+        diagData.inputs = opts.inputs;
+    if (opts?.decision !== undefined)
+        diagData.decision = opts.decision;
+    if (opts?.reasoning !== undefined)
+        diagData.reasoning = opts.reasoning;
+    if (opts?.data && typeof opts.data === "object") {
+        Object.assign(diagData, opts.data);
+    }
+    hookLog("debug", hookName, `[DIAG:${phase}] ${summary}`, {
+        component: opts?.component ?? "diag",
+        data: diagData,
+    });
+}
+/**
+ * Backward-compatible wrapper matching old hook_utils.log_hook_error signature.
+ * See SPEC.md §3.6
+ */
+export function logHookError(hookName, error, hookEvent = "unknown", tracebackStr = "") {
+    const errStr = typeof error === "string" ? error : String(error);
+    const msg = errStr.replaceAll(/[\n\r]/g, " ").slice(0, 200);
+    const errType = typeof error === "object" && error !== null
+        ? error.constructor.name
+        : "Error";
+    hookLog("error", hookName, `[${hookEvent}] ${errType}: ${msg}`, {
+        traceback_str: tracebackStr,
+        stderr: true,
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Canonical model ID constants — single source of truth.
+ * All model IDs used across the system should reference these constants.
+ */
+export declare const CLAUDE_MODELS: {
+    readonly haiku: "claude-haiku-4-5-20251001";
+    readonly sonnet: "claude-sonnet-4-6";
+    readonly opus: "claude-opus-4-6";
+};
+export declare const CODEX_MODELS: {
+    readonly spark: "gpt-5.3-codex-spark";
+    readonly codex: "gpt-5.4";
+    readonly gpt: "gpt-5.4";
+};

package/dist/lib/runtime/models.js

@@ -0,0 +1,14 @@
+/**
+ * Canonical model ID constants — single source of truth.
+ * All model IDs used across the system should reference these constants.
+ */
+export const CLAUDE_MODELS = {
+    haiku: "claude-haiku-4-5-20251001",
+    sonnet: "claude-sonnet-4-6",
+    opus: "claude-opus-4-6",
+};
+export const CODEX_MODELS = {
+    spark: "gpt-5.3-codex-spark",
+    codex: "gpt-5.4",
+    gpt: "gpt-5.4",
+};

package/dist/lib/runtime/platform-adapter.d.ts

@@ -0,0 +1,7 @@
+export type TmuxColorMode = 'c256' | 'truecolor';
+export declare function isWindowsPlatform(platform?: NodeJS.Platform): boolean;
+export declare function isNonWindowsPlatform(platform?: NodeJS.Platform): boolean;
+export declare function commandLookupBinary(platform?: NodeJS.Platform): 'where.exe' | 'which';
+export declare function shouldUseShell(platform?: NodeJS.Platform): boolean;
+export declare function resolveTmuxColorModeForPlatform(_platform?: NodeJS.Platform): TmuxColorMode;
+export declare function applyTmuxLaunchEnv(envVars: Record<string, string>, _platform?: NodeJS.Platform): Record<string, string>;

package/dist/lib/runtime/platform-adapter.js

@@ -0,0 +1,21 @@
+export function isWindowsPlatform(platform = process.platform) {
+    return platform === 'win32';
+}
+export function isNonWindowsPlatform(platform = process.platform) {
+    return !isWindowsPlatform(platform);
+}
+export function commandLookupBinary(platform = process.platform) {
+    return isWindowsPlatform(platform) ? 'where.exe' : 'which';
+}
+export function shouldUseShell(platform = process.platform) {
+    return isWindowsPlatform(platform);
+}
+export function resolveTmuxColorModeForPlatform(_platform) {
+    // Always truecolor — Windows now uses psmux (native ConPTY) which supports truecolor natively.
+    // The c256 degradation was only needed for tmux-via-MSYS2-bash.
+    return 'truecolor';
+}
+export function applyTmuxLaunchEnv(envVars, _platform) {
+    // Always inject truecolor — psmux on Windows and tmux on Unix both support it.
+    return { COLORTERM: 'truecolor', ...envVars };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Shared preflight health check for provider+model availability.
+ * Extracted from plan-review/lib/preflight.ts for reuse by unknown hook.
+ *
+ * Validates that a CLI tool + model combo works by running a minimal "ping" request.
+ */
+export interface PreflightCommandConfig {
+    cliName: string;
+    buildArgs: (model: string) => string[];
+    input: string;
+}
+export interface PreflightCheckResult {
+    provider: string;
+    model: string;
+    available: boolean;
+    latencyMs: number;
+    error?: string;
+}
+export declare function classifyError(stderr: string, exitCode: number | null, killed: boolean, signal: string | null): string;
+/**
+ * Check if a single provider:model combo is available.
+ * Takes a PreflightCommandConfig so callers define their own CLI args.
+ */
+export declare function checkProviderModel(provider: string, model: string, config: PreflightCommandConfig, timeoutMs: number, hook?: string): Promise<PreflightCheckResult>;

package/dist/lib/runtime/preflight.js

@@ -0,0 +1,65 @@
+/**
+ * Shared preflight health check for provider+model availability.
+ * Extracted from plan-review/lib/preflight.ts for reuse by unknown hook.
+ *
+ * Validates that a CLI tool + model combo works by running a minimal "ping" request.
+ */
+import { logDebug, logWarn } from "./logger.js";
+import { findExecutable, execFileAsync, getInternalSubprocessEnv } from "./subprocess-utils.js";
+// ---------------------------------------------------------------------------
+// Error Classification
+// ---------------------------------------------------------------------------
+export function classifyError(stderr, exitCode, killed, signal) {
+    if (killed || signal === "SIGTERM")
+        return "Preflight timed out";
+    if (/model.*not found|not available/i.test(stderr))
+        return "Model not available for this account";
+    if (/rate limit|429/i.test(stderr))
+        return "Rate limited";
+    if (/auth|api key|401/i.test(stderr))
+        return "Authentication failed";
+    if (/quota|billing/i.test(stderr))
+        return "Quota/billing issue";
+    return `Exit code ${exitCode}`;
+}
+// ---------------------------------------------------------------------------
+// Single Provider+Model Check
+// ---------------------------------------------------------------------------
+/**
+ * Check if a single provider:model combo is available.
+ * Takes a PreflightCommandConfig so callers define their own CLI args.
+ */
+export async function checkProviderModel(provider, model, config, timeoutMs, hook = "preflight") {
+    const cliPath = findExecutable(config.cliName);
+    if (!cliPath) {
+        return { provider, model, available: false, latencyMs: 0, error: `CLI '${config.cliName}' not found on PATH` };
+    }
+    const start = Date.now();
+    try {
+        const env = getInternalSubprocessEnv();
+        const result = await execFileAsync(cliPath, config.buildArgs(model), {
+            input: config.input,
+            timeout: timeoutMs,
+            env: env,
+            maxBuffer: 1 * 1024 * 1024,
+            shell: process.platform === "win32",
+        });
+        const latencyMs = Date.now() - start;
+        if (result.killed || result.signal === "SIGTERM") {
+            return { provider, model, available: false, latencyMs, error: "Preflight timed out" };
+        }
+        if (result.exitCode !== 0) {
+            const error = classifyError(result.stderr, result.exitCode, result.killed, result.signal);
+            logWarn(hook, `${provider}:${model} failed: ${error} (stderr: ${result.stderr.slice(-200)})`);
+            return { provider, model, available: false, latencyMs, error };
+        }
+        logDebug(hook, `${provider}:${model} passed (${latencyMs}ms)`);
+        return { provider, model, available: true, latencyMs };
+    }
+    catch (error_) {
+        const latencyMs = Date.now() - start;
+        const error = error_ instanceof Error ? error_.message : String(error_);
+        logWarn(hook, `${provider}:${model} exception: ${error}`);
+        return { provider, model, available: false, latencyMs, error };
+    }
+}

package/dist/lib/runtime/sentinel-ipc.d.ts

@@ -0,0 +1,14 @@
+export interface SentinelIpcPaths {
+    tmpDir: string;
+    inputPath: string;
+    stdoutPath: string;
+    stderrPath: string;
+    sentinelPath: string;
+}
+export declare function createSentinelIpcPaths(prefix: string): SentinelIpcPaths;
+export declare function buildShellCaptureScript(command: string, paths: Pick<SentinelIpcPaths, 'inputPath' | 'stdoutPath' | 'stderrPath' | 'sentinelPath'>, quote: (input: string) => string): string;
+export declare function waitForSentinelFile(sentinelPath: string, timeoutMs: number, pollIntervalMs?: number): Promise<boolean>;
+export declare function readSentinelExitCode(sentinelPath: string, fallback?: number): number;
+export declare function readTextIfExists(filePath: string): string;
+export declare function cleanupSentinelIpc(paths: Pick<SentinelIpcPaths, 'tmpDir'>): void;
+export declare function cleanupSentinelPath(sentinelPath: string | undefined): void;

package/dist/lib/runtime/sentinel-ipc.js

@@ -0,0 +1,67 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import path from 'node:path';
+function sanitizePrefix(prefix) {
+    return prefix.replaceAll(/[^a-zA-Z0-9_-]/g, '-');
+}
+export function createSentinelIpcPaths(prefix) {
+    const safePrefix = sanitizePrefix(prefix);
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `${safePrefix}-`));
+    return {
+        tmpDir,
+        inputPath: path.join(tmpDir, 'input.txt'),
+        stdoutPath: path.join(tmpDir, 'stdout.txt'),
+        stderrPath: path.join(tmpDir, 'stderr.txt'),
+        sentinelPath: path.join(tmpDir, 'sentinel.txt'),
+    };
+}
+export function buildShellCaptureScript(command, paths, quote) {
+    return [
+        command,
+        `< ${quote(paths.inputPath)}`,
+        `> ${quote(paths.stdoutPath)}`,
+        `2> ${quote(paths.stderrPath)}`,
+        `; echo $? > ${quote(paths.sentinelPath)}`,
+    ].join(' ');
+}
+export async function waitForSentinelFile(sentinelPath, timeoutMs, pollIntervalMs = 250) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (fs.existsSync(sentinelPath))
+            return true;
+        await new Promise((resolve) => {
+            setTimeout(resolve, pollIntervalMs);
+        });
+    }
+    return fs.existsSync(sentinelPath);
+}
+export function readSentinelExitCode(sentinelPath, fallback = 1) {
+    if (!fs.existsSync(sentinelPath))
+        return fallback;
+    const raw = fs.readFileSync(sentinelPath, 'utf8').trim();
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function readTextIfExists(filePath) {
+    if (!filePath || !fs.existsSync(filePath))
+        return '';
+    return fs.readFileSync(filePath, 'utf8');
+}
+export function cleanupSentinelIpc(paths) {
+    try {
+        fs.rmSync(paths.tmpDir, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}
+export function cleanupSentinelPath(sentinelPath) {
+    if (!sentinelPath)
+        return;
+    try {
+        fs.rmSync(path.dirname(sentinelPath), { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Shared I/O for state.json — read, write, serialize.
+ * Extracted to avoid circular deps between context-store and task-tracker.
+ * See SPEC.md §7.1
+ */
+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.
+ */
+export declare function toDict(state: ContextState): Record<string, unknown>;
+/**
+ * Get path to state.json for a context.
+ */
+export declare function statePath(contextId: string, projectRoot?: string): string;
+/**
+ * Read and parse state.json for a context.
+ * Applies legacy mode migration. Returns null if file doesn't exist or is corrupt.
+ */
+export declare function readStateJson(contextId: string, projectRoot?: string): ContextState | null;
+/**
+ * Atomically write state.json for a context.
+ * Returns [success, error].
+ */
+export declare function writeStateJson(contextId: string, state: ContextState, projectRoot?: string): [boolean, string | null];
+/**
+ * Construct a ContextState from a dict, migrating old mode names.
+ * Only includes fields that are present in the source data (preserves null-stripping).
+ */
+export declare function dictToState(data: Record<string, unknown>): ContextState;

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

@@ -0,0 +1,174 @@
+/**
+ * Shared I/O for state.json — read, write, serialize.
+ * Extracted to avoid circular deps between context-store and task-tracker.
+ * See SPEC.md §7.1
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./atomic-write.js";
+import { getContextDir } from "./constants.js";
+import { logWarn } from "./logger.js";
+/** Mode migration from legacy context_manager values. */
+const MODE_MIGRATION = {
+    none: "idle",
+    planning: "idle",
+    pending_implementation: "has_staged_work",
+    implementing: "active",
+};
+/**
+ * Serialize a ContextState for JSON output.
+ * Omits null/undefined keys but 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) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Migrate old consumed flags to unified work_consumed.
+ * Runs on every state.json read for transparent backward compatibility.
+ * Idempotent: safe to run multiple times.
+ */
+function migrateConsumedFlags(data) {
+    const legacy = data;
+    // Skip if already migrated (check both fields and mode)
+    const alreadyMigrated = typeof legacy.work_consumed === "boolean" &&
+        legacy.mode !== "has_plan" &&
+        legacy.mode !== "has_handoff";
+    if (alreadyMigrated)
+        return;
+    const hasPlan = Boolean(legacy.plan_path && legacy.plan_hash);
+    const hasHandoff = Boolean(legacy.handoff_path);
+    // Migrate consumed flag (plan takes precedence if both exist)
+    if (hasPlan && typeof legacy.plan_consumed === "boolean") {
+        data.work_consumed = legacy.plan_consumed;
+    }
+    else if (hasHandoff && typeof legacy.handoff_consumed === "boolean") {
+        data.work_consumed = legacy.handoff_consumed;
+    }
+    else {
+        data.work_consumed = false;
+    }
+    // Migrate mode: has_plan/has_handoff → has_staged_work
+    if (legacy.mode === "has_plan" || legacy.mode === "has_handoff") {
+        const artifactType = legacy.mode === "has_handoff" ? "handoff" : "plan";
+        data.mode = "has_staged_work";
+        data.next_artifact_type = artifactType;
+    }
+    // Set next_artifact_type based on which artifact exists
+    if (!legacy.next_artifact_type) {
+        if (hasPlan && hasHandoff) {
+            // Both exist - conflict resolution: plan priority during migration
+            // (Cannot determine "latest" without timestamps - plan takes precedence)
+            data.next_artifact_type = "plan";
+            data.handoff_path = null;
+        }
+        else if (hasPlan) {
+            data.next_artifact_type = "plan";
+        }
+        else if (hasHandoff) {
+            data.next_artifact_type = "handoff";
+        }
+    }
+    // Delete old flags (clean cut migration)
+    delete data.plan_consumed;
+    delete data.handoff_consumed;
+}
+/**
+ * Get path to state.json for a context.
+ */
+export function statePath(contextId, projectRoot) {
+    return path.join(getContextDir(contextId, projectRoot), "state.json");
+}
+/**
+ * Read and parse state.json for a context.
+ * Applies legacy mode migration. Returns null if file doesn't exist or is corrupt.
+ */
+export function readStateJson(contextId, projectRoot) {
+    const sp = statePath(contextId, projectRoot);
+    if (!fs.existsSync(sp))
+        return null;
+    try {
+        const raw = fs.readFileSync(sp, "utf8");
+        const data = JSON.parse(raw);
+        migrateConsumedFlags(data); // Migrate before dictToState
+        return dictToState(data);
+    }
+    catch (error) {
+        logWarn("state_io", `Failed to read state.json for '${contextId}': ${error}`);
+        return null;
+    }
+}
+/**
+ * Atomically write state.json for a context.
+ * Returns [success, error].
+ */
+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);
+}
+/**
+ * Construct a ContextState from a dict, migrating old mode names.
+ * Only includes fields that are present in the source data (preserves null-stripping).
+ */
+export function dictToState(data) {
+    // Validate required fields
+    if (typeof data.id !== "string" || !data.id) {
+        throw new Error("dictToState: missing or invalid required field 'id'");
+    }
+    const rawMode = typeof data.mode === "string" ? data.mode : "idle";
+    const mode = (MODE_MIGRATION[rawMode] ?? rawMode);
+    const state = {
+        id: data.id,
+        status: data.status ?? "active",
+        summary: data.summary ?? "",
+        method: data.method ?? "",
+        tags: data.tags ?? [],
+        created_at: data.created_at ?? "",
+        last_active: data.last_active ?? "",
+        mode,
+        plan_anchors: data.plan_anchors ?? [],
+        work_consumed: data.work_consumed ?? false,
+        session_ids: data.session_ids ?? [],
+        tasks: data.tasks ?? [],
+    };
+    // Only set nullable fields if they exist in the source data
+    if ("plan_path" in data)
+        state.plan_path = data.plan_path;
+    if ("plan_hash" in data)
+        state.plan_hash = data.plan_hash;
+    if ("plan_signature" in data)
+        state.plan_signature = data.plan_signature;
+    if ("plan_id" in data)
+        state.plan_id = data.plan_id;
+    if ("handoff_path" in data)
+        state.handoff_path = data.handoff_path;
+    if ("next_artifact_type" in data)
+        state.next_artifact_type = data.next_artifact_type;
+    if ("last_session" in data)
+        state.last_session = data.last_session;
+    // Migration: plan_hash_consumed (added in multi-plan context fix)
+    if ("plan_hash_consumed" in data) {
+        state.plan_hash_consumed = data.plan_hash_consumed;
+    }
+    else {
+        state.plan_hash_consumed = null; // Default for old contexts
+    }
+    // Preserve method-specific extension data (e.g., cc_native) that isn't
+    // part of the core ContextState interface. Without this, round-trip
+    // read→write cycles silently drop extension fields.
+    for (const key of Object.keys(data)) {
+        if (!(key in state)) {
+            state[key] = data[key];
+        }
+    }
+    return state;
+}

package/dist/lib/runtime/stop-words.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stop words for context ID generation.
+ *
+ * Generated from analysis of 1,424 prompts, context summaries, and plan files.
+ * Words that appear frequently but don't help identify the specific task.
+ *
+ * ACTION VERBS ARE INTENTIONALLY EXCLUDED:
+ * add, fix, update, create, implement, refactor, migrate, debug, remove, change,
+ * move, rename, delete, build, test, deploy, verify, analyze, modify, write, run,
+ * check, replace, save, sync, load, extract, install, clean, merge, etc.
+ *
+ * See SPEC.md §14.1
+ */
+export declare const STOP_WORDS: ReadonlySet<string>;
+/**
+ * Filter stop words from text.
+ * Splits on whitespace, removes words in STOP_WORDS set and single-char words.
+ * See SPEC.md §6.4
+ */
+export declare function filterStopWords(text: string): string;