aiwcli 0.12.3 → 0.12.6

package/dist/templates/_shared/lib-ts/base/state-io.ts

@@ -19,6 +19,18 @@ const MODE_MIGRATION: Record<string, Mode> = {
   implementing: "active",
 };
 
+/** Legacy state data structure for migration type safety. */
+interface LegacyStateData {
+  mode?: string;
+  plan_path?: string | null;
+  plan_hash?: string | null;
+  handoff_path?: string | null;
+  plan_consumed?: boolean;
+  handoff_consumed?: boolean;
+  work_consumed?: boolean;
+  next_artifact_type?: "plan" | "handoff" | null;
+}
+
 /**
  * Serialize a ContextState for JSON output.
  * Omits null/undefined keys but keeps false, 0, empty string, and empty arrays.
@@ -33,6 +45,59 @@ export function toDict(state: ContextState): Record<string, unknown> {
   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: Record<string, unknown>): void {
+  const legacy = data as LegacyStateData;
+
+  // 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 as Record<string, unknown>).work_consumed = legacy.plan_consumed;
+  } else if (hasHandoff && typeof legacy.handoff_consumed === "boolean") {
+    (data as Record<string, unknown>).work_consumed = legacy.handoff_consumed;
+  } else {
+    (data as Record<string, unknown>).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 as Record<string, unknown>).mode = "has_staged_work";
+    (data as Record<string, unknown>).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 as Record<string, unknown>).next_artifact_type = "plan";
+      (data as Record<string, unknown>).handoff_path = null;
+    } else if (hasPlan) {
+      (data as Record<string, unknown>).next_artifact_type = "plan";
+    } else if (hasHandoff) {
+      (data as Record<string, unknown>).next_artifact_type = "handoff";
+    }
+  }
+
+  // Delete old flags (clean cut migration)
+  delete (data as Record<string, unknown>).plan_consumed;
+  delete (data as Record<string, unknown>).handoff_consumed;
+}
+
 /**
  * Get path to state.json for a context.
  */
@@ -54,6 +119,7 @@ export function readStateJson(
   try {
     const raw = fs.readFileSync(sp, "utf-8");
     const data = JSON.parse(raw) as Record<string, any>;
+    migrateConsumedFlags(data); // Migrate before dictToState
     return dictToState(data);
   } catch (e: any) {
     logWarn("state_io", `Failed to read state.json for '${contextId}': ${e}`);
@@ -82,8 +148,14 @@ export function writeStateJson(
  * 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: Record<string, any>): ContextState {
-  const rawMode: string = data.mode ?? "idle";
+export function dictToState(data: Record<string, unknown>): ContextState {
+  // Validate required fields
+  if (typeof data.id !== "string" || !data.id) {
+    throw new Error("dictToState: missing or invalid required field 'id'");
+  }
+
+  const rawMode: string =
+    typeof data.mode === "string" ? data.mode : "idle";
   const mode: Mode = (MODE_MIGRATION[rawMode] ?? rawMode) as Mode;
 
   const state: any = {
@@ -96,8 +168,7 @@ export function dictToState(data: Record<string, any>): ContextState {
     last_active: data.last_active ?? "",
     mode,
     plan_anchors: data.plan_anchors ?? [],
-    plan_consumed: data.plan_consumed ?? false,
-    handoff_consumed: data.handoff_consumed ?? false,
+    work_consumed: data.work_consumed ?? false,
     session_ids: data.session_ids ?? [],
     tasks: data.tasks ?? [],
   };
@@ -108,6 +179,7 @@ export function dictToState(data: Record<string, any>): ContextState {
   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)

package/dist/templates/_shared/lib-ts/base/subprocess-utils.ts

@@ -4,6 +4,54 @@
  */
 
 import { execSync, execFile } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+
+// ─── Child Process Cleanup ─────────────────────────────────────────────────
+//
+// Track all spawned child processes to prevent orphaned Node.js processes.
+//
+// Problem: When parent process exits (Ctrl+C, abnormal termination), child
+// processes spawned via execFile can become orphaned if they haven't completed.
+//
+// Solution: Track children in a Set, register exit/signal handlers to kill all
+// tracked children before parent exits.
+//
+// Windows behavior: On Windows with shell:true, execFile spawns cmd.exe which
+// spawns the actual node.exe. Using SIGKILL ensures both are terminated.
+
+const childProcesses = new Set<ChildProcess>();
+
+/**
+ * Cleanup all tracked child processes.
+ * Called by exit and signal handlers.
+ */
+function cleanupChildren(): void {
+  childProcesses.forEach((child) => {
+    try {
+      // Use SIGKILL for forceful termination (important on Windows with shell)
+      child.kill("SIGKILL");
+    } catch {
+      // Ignore errors (child may have already exited)
+    }
+  });
+  childProcesses.clear();
+}
+
+// Register exit handler (runs when process exits normally)
+process.on("exit", () => {
+  cleanupChildren();
+});
+
+// Register signal handlers (Ctrl+C, kill command)
+process.on("SIGINT", () => {
+  cleanupChildren();
+  process.exit(130); // Standard exit code for SIGINT
+});
+
+process.on("SIGTERM", () => {
+  cleanupChildren();
+  process.exit(143); // Standard exit code for SIGTERM
+});
 
 /**
  * Check if this is an internal subprocess call.
@@ -172,6 +220,14 @@ export function execFileAsync(
       },
     );
 
+    // Track child process for cleanup on abnormal parent exit
+    childProcesses.add(child);
+
+    // Remove from tracking when child exits (normal completion)
+    child.on("exit", () => {
+      childProcesses.delete(child);
+    });
+
     // Pipe input to stdin if provided
     if (options?.input != null && child.stdin) {
       child.stdin.write(options.input);

package/dist/templates/_shared/lib-ts/context/context-formatter.ts

@@ -21,8 +21,7 @@ const MAX_PLAN_INLINE_CHARS = 30_000;
 
 const MODE_DISPLAY_MAP: Record<string, string> = {
   idle: "",
-  has_plan: "[Plan Ready]",
-  has_handoff: "[Handoff Ready]",
+  has_staged_work: "[Staged]", // CHANGED: unified mode (plan or handoff)
   active: "[Active]",
 };
 
@@ -449,6 +448,7 @@ const KNOWN_FOLDERS: Record<string, string> = {
   "session-transcripts": "JSONL records of previous agent sessions — read these to understand prior work",
   "handoffs": "Structured briefing documents for session continuity",
   "reviews": "Plan review artifacts (reviewer verdicts, corroboration reports)",
+  "notes": "Analysis files, reports, and documentation that don't belong in the codebase",
 };
 
 function collectFolderPath(contextId: string, contextDir: string, state: ContextState): string | null {
@@ -532,12 +532,18 @@ function collectSessionStats(contextId: string, contextDir: string, state: Conte
   return line;
 }
 
+function collectNotesGuidance(contextId: string, contextDir: string, state: ContextState): string | null {
+  const notesDir = path.join(contextDir, "notes");
+  return `**Notes:** Put notes and files that don't belong in the codebase here. Reference them in other documents as needed: \`${notesDir}\``;
+}
+
 /** Ordered list of inventory collectors. Append new collectors here. */
 const INVENTORY_COLLECTORS: InventoryCollector[] = [
   collectFolderPath,
   collectStatePointers,
   collectFolderInventory,
   collectSessionStats,
+  collectNotesGuidance,
 ];
 
 /**

package/dist/templates/_shared/lib-ts/context/context-selector.ts

@@ -14,30 +14,30 @@
  */
 
 import * as crypto from "node:crypto";
-
+import {
+  getContext,
+  getAllContexts,
+  getContextBySessionId,
+  createContextFromPrompt,
+  createContext,
+  completeContext,
+  bindSession,
+  updateMode,
+  determineArtifactType,
+} from "./context-store.js";
 import {
   formatActiveContextReminder,
-  formatActiveContinuation as _formatActiveContinuation,
-  formatCommandFeedback,
   formatContextCreated,
   formatContextPickerStderr,
+  formatCommandFeedback,
   formatHandoffContinuation,
   formatPlanContinuation,
+  formatActiveContinuation,
 } from "./context-formatter.js";
-import {
-  bindSession,
-  completeContext,
-  createContext,
-  createContextFromPrompt,
-  getAllContexts,
-  getContext,
-  getContextBySessionId,
-  updateMode,
-} from "./context-store.js";
 import { normalizePlanContent } from "./plan-manager.js";
-import { logDebug, logError, logInfo, logWarn as _logWarn } from "../base/logger.js";
 import { isInternalCall } from "../base/subprocess-utils.js";
-import type { CaretCommand, ContextState } from "../types.js";
+import { logDebug, logInfo, logWarn, logError } from "../base/logger.js";
+import type { ContextState, CaretCommand } from "../types.js";
 
 /** Minimum characters required for new context description. */
 const MIN_NEW_CONTEXT_CHARS = 10;
@@ -50,6 +50,8 @@ export class BlockRequest extends Error {
   constructor(message: string) {
     super(message);
     this.name = "BlockRequest";
+    // Maintains proper prototype chain when transpiled to ES5
+    Object.setPrototypeOf(this, BlockRequest.prototype);
   }
 }
 
@@ -66,7 +68,7 @@ export class BlockRequest extends Error {
 export function resolveContextByPrefix(
   query: string,
   contexts: ContextState[],
-): [null | number, null | string] {
+): [number | null, string | null] {
   const q = query.toLowerCase();
   const available = contexts.map(c => c.id).join(", ");
 
@@ -108,7 +110,7 @@ export function resolveContextByPrefix(
 export function parseChainedCaret(
   prompt: string,
   contexts: ContextState[],
-): [CaretCommand | null, null | string] {
+): [CaretCommand | null, string | null] {
   if (!prompt.startsWith("^")) return [null, null];
 
   const match = prompt.match(/^\^(\S+)(?:\s+(.*))?$/s);
@@ -121,7 +123,7 @@ export function parseChainedCaret(
 
   // ^N shorthand
   if (/^\d+$/.test(commandStr)) {
-    const num = Number.parseInt(commandStr, 10);
+    const num = parseInt(commandStr, 10);
     if (num === 0) {
       if (remaining.length < MIN_NEW_CONTEXT_CHARS) {
         return [null,
@@ -131,25 +133,21 @@ export function parseChainedCaret(
           `Example: ^0 implement user authentication with JWT tokens`,
         ];
       }
-
       return [{ ends: [], select: null, new_context_desc: remaining, remaining_prompt: "" }, null];
     }
-
     if (num < 1 || num > contexts.length) {
       if (contexts.length === 0) {
         return [null, "No existing contexts. Use ^0 <description> to create a new one."];
       }
-
       return [null, `Invalid selection. Choose 1-${contexts.length} for existing contexts, or ^0 for new.`];
     }
-
     const ctx = contexts[num - 1]!;
     return [{ ends: [], select: ctx.id, new_context_desc: null, remaining_prompt: remaining }, null];
   }
 
   // Parse chained commands
   const ends: string[] = [];
-  let select: null | string = null;
+  let select: string | null = null;
   let pos = 0;
 
   while (pos < commandStr.length) {
@@ -179,13 +177,11 @@ export function parseChainedCaret(
         if (numStart === pos) {
           return [null, `Expected number, '*', or ':prefix' after 'E' at position ${numStart + 1}`];
         }
-
-        const num = Number.parseInt(commandStr.slice(numStart, pos), 10);
+        const num = parseInt(commandStr.slice(numStart, pos), 10);
         if (num < 1 || num > contexts.length) {
           if (contexts.length === 0) return [null, "No contexts to end."];
           return [null, `Context ^E${num} invalid. Choose 1-${contexts.length}.`];
         }
-
         if (pos < commandStr.length && commandStr[pos] === "+") {
           pos++;
           for (let i = num; i <= contexts.length; i++) {
@@ -215,16 +211,13 @@ export function parseChainedCaret(
         if (numStart === pos) {
           return [null, `Expected number or ':prefix' after 'S' at position ${numStart + 1}`];
         }
-
-        const num = Number.parseInt(commandStr.slice(numStart, pos), 10);
+        const num = parseInt(commandStr.slice(numStart, pos), 10);
         if (num < 1 || num > contexts.length) {
           if (contexts.length === 0) return [null, "No contexts to select."];
           return [null, `Context ^S${num} invalid. Choose 1-${contexts.length}.`];
         }
-
         ctx = contexts[num - 1]!;
       }
-
       if (select === null) select = ctx.id;
     } else {
       return [null,
@@ -284,9 +277,9 @@ function matchPlanContent(prompt: string, hasPlanContexts: ContextState[]): Cont
   }
 
   // Tier 4 (legacy): Signature match
-  const promptHead = new Set(prompt.slice(0, 500));
+  const promptHead = prompt.slice(0, 500);
   for (const ctx of hasPlanContexts) {
-    if (ctx.plan_signature && promptHead.has(ctx.plan_signature)) {
+    if (ctx.plan_signature && promptHead.includes(ctx.plan_signature)) {
       logDebug("context_selector", `Tier 4 legacy signature match: ${ctx.id}`);
       return ctx;
     }
@@ -302,15 +295,15 @@ function matchPlanContent(prompt: string, hasPlanContexts: ContextState[]): Cont
 function createNewContext(
   prompt: string,
   projectRoot?: string,
-): [null | string, string, null | string] {
+): [string | null, string, string | null] {
   try {
     const newCtx = createContextFromPrompt(prompt, projectRoot);
     updateMode(newCtx.id, "active", projectRoot);
     newCtx.mode = "active";
     logInfo("context_selector", `Auto-created context: ${newCtx.id}`);
     return [newCtx.id, "auto_created", formatContextCreated(newCtx)];
-  } catch (error: any) {
-    logError("context_selector", `Primary context creation failed: ${error}`);
+  } catch (e: any) {
+    logError("context_selector", `Primary context creation failed: ${e}`);
     try {
       const now = new Date();
       const yy = String(now.getFullYear()).slice(2);
@@ -330,8 +323,8 @@ function createNewContext(
       newCtx.mode = "active";
       logInfo("context_selector", `Fallback context created: ${newCtx.id}`);
       return [newCtx.id, "auto_created_fallback", formatContextCreated(newCtx)];
-    } catch (error: any) {
-      logError("context_selector", `ALL context creation failed: ${error}`);
+    } catch (e2: any) {
+      logError("context_selector", `ALL context creation failed: ${e2}`);
       return [null, "creation_failed", null];
     }
   }
@@ -345,7 +338,7 @@ function handleCaretCommand(
   prompt: string,
   contexts: ContextState[],
   projectRoot?: string,
-): [null | string, string, null | string] {
+): [string | null, string, string | null] {
   if (contexts.length === 0) {
     const match = prompt.match(/^\^(\S+)(?:\s+(.*))?$/s);
     if (!match) {
@@ -354,16 +347,14 @@ function handleCaretCommand(
         "Example: ^0 implement user authentication system",
       );
     }
-
     const prefixValue = match[1]!;
     const remaining = match[2] ?? "";
-    if (!/^\d+$/.test(prefixValue) || Number.parseInt(prefixValue, 10) !== 0) {
+    if (!/^\d+$/.test(prefixValue) || parseInt(prefixValue, 10) !== 0) {
       throw new BlockRequest(
         "No existing contexts to select. Use ^0 <description> to create a new context.\n" +
         "Example: ^0 implement user authentication system",
       );
     }
-
     const description = remaining.trim();
     if (description.length < MIN_NEW_CONTEXT_CHARS) {
       throw new BlockRequest(
@@ -373,7 +364,6 @@ function handleCaretCommand(
         `Example: ^0 implement user authentication with JWT tokens`,
       );
     }
-
     return createNewContext(description, projectRoot);
   }
 
@@ -387,7 +377,6 @@ function handleCaretCommand(
     if (!ctxToEnd) {
       throw new BlockRequest(`Context '${ctxId}' no longer exists.\n` + formatContextPickerStderr(contexts));
     }
-
     completeContext(ctxToEnd.id, projectRoot);
     endedContexts.push(ctxToEnd);
     logInfo("context_selector", `Ended context: ${ctxToEnd.id}`);
@@ -398,10 +387,9 @@ function handleCaretCommand(
     if (ctxId && endedContexts.length > 0) {
       const newCtx = getContext(ctxId, projectRoot);
       const feedback = formatCommandFeedback(endedContexts, newCtx);
-      return [ctxId, method === "creation_failed" ? method : "caret_new", feedback];
+      return [ctxId, method !== "creation_failed" ? "caret_new" : method, feedback];
     }
-
-    return [ctxId, method === "creation_failed" ? method : "caret_new", output];
+    return [ctxId, method !== "creation_failed" ? "caret_new" : method, output];
   }
 
   if (cmd.select) {
@@ -409,7 +397,6 @@ function handleCaretCommand(
     if (!selectedCtx) {
       throw new BlockRequest(`Context '${cmd.select}' no longer exists.\n` + formatContextPickerStderr(contexts));
     }
-
     logInfo("context_selector", `Caret-selected context: ${selectedCtx.id}`);
     return [selectedCtx.id, "caret_select", formatCommandFeedback(endedContexts, selectedCtx)];
   }
@@ -424,7 +411,6 @@ function handleCaretCommand(
         "Example: implement user authentication system",
       );
     }
-
     throw new BlockRequest(
       feedback + "\nNo context selected.\n\nSelect a context to continue:\n" +
       formatContextPickerStderr(remainingContexts),
@@ -449,7 +435,7 @@ export function determineContext(
   prompt: string,
   sessionId?: string,
   projectRoot?: string,
-): [null | string, string, null | string] {
+): [string | null, string, string | null] {
   if (isInternalCall()) {
     logDebug("context_selector", "Skipping: internal subprocess call");
     return [null, "skip_internal", null];
@@ -477,7 +463,6 @@ export function determineContext(
         "Example: implement user authentication system",
       );
     }
-
     throw new BlockRequest(formatContextPickerStderr(contexts));
   }
 
@@ -486,28 +471,52 @@ export function determineContext(
     return handleCaretCommand(prompt, contexts, projectRoot);
   }
 
-  // --- Case 3: plan_content_match (fallback) ---
-  const hasPlanContexts = getAllContexts("active", projectRoot).filter(c => c.mode === "has_plan");
-  if (hasPlanContexts.length > 0) {
-    const matched = matchPlanContent(prompt, hasPlanContexts);
-    if (matched) {
-      if (sessionId) bindSession(matched.id, sessionId, projectRoot);
-      updateMode(matched.id, "active", projectRoot, { plan_consumed: true });
-      matched.mode = "active";
-      logInfo("context_selector", `Plan match (fallback): ${matched.id}`);
-      return [matched.id, "plan_content_match", formatPlanContinuation(matched, projectRoot)];
+  // --- Case 3: Staged work match (CHANGED: unified mode) ---
+  const stagedContexts = getAllContexts("active", projectRoot).filter(
+    (c) => c.mode === "has_staged_work",
+  );
+
+  if (stagedContexts.length > 0) {
+    // Separate by artifact type
+    const planContexts = stagedContexts.filter(
+      (c) => determineArtifactType(c) === "plan",
+    );
+    const handoffContexts = stagedContexts.filter(
+      (c) => determineArtifactType(c) === "handoff",
+    );
+
+    // Try plan matching first (content-based matching)
+    if (planContexts.length > 0) {
+      const matched = matchPlanContent(prompt, planContexts);
+      if (matched) {
+        if (sessionId) bindSession(matched.id, sessionId, projectRoot);
+        updateMode(matched.id, "active", projectRoot, {
+          work_consumed: true, // CHANGED: unified flag
+          plan_hash_consumed: matched.plan_hash,
+        });
+        matched.mode = "active";
+        logInfo("context_selector", `Plan match (fallback): ${matched.id}`);
+        return [
+          matched.id,
+          "plan_content_match",
+          formatPlanContinuation(matched, projectRoot),
+        ];
+      }
     }
-  }
 
-  // --- Case 3b: handoff_match (fallback) ---
-  const hasHandoffContexts = getAllContexts("active", projectRoot).filter(c => c.mode === "has_handoff");
-  if (hasHandoffContexts.length > 0) {
-    const target = hasHandoffContexts[0]!;
-    if (sessionId) bindSession(target.id, sessionId, projectRoot);
-    updateMode(target.id, "active", projectRoot, { handoff_consumed: true });
-    target.mode = "active";
-    logInfo("context_selector", `Handoff match (fallback): ${target.id}`);
-    return [target.id, "handoff_match", formatHandoffContinuation(target, projectRoot)];
+    // Fallback to handoff (pick first - no content matching)
+    if (handoffContexts.length > 0) {
+      const target = handoffContexts[0]!;
+      if (sessionId) bindSession(target.id, sessionId, projectRoot);
+      updateMode(target.id, "active", projectRoot, { work_consumed: true }); // CHANGED
+      target.mode = "active";
+      logInfo("context_selector", `Handoff match (fallback): ${target.id}`);
+      return [
+        target.id,
+        "handoff_match",
+        formatHandoffContinuation(target, projectRoot),
+      ];
+    }
   }
 
   // --- Case 4: default ---