@tyvm/knowhow 0.0.148 → 0.0.150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.148",
+  "version": "0.0.150",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/agents/base/base.ts

@@ -1670,8 +1670,7 @@ export abstract class BaseAgent implements IAgent {
     const response = await this.createAgentCompletion({
       model,
       messages: taskBreakdownMessages,
-      tools: this.getEnabledTools(),
-      tool_choice: "auto",
+      tool_choice: "none",
       long_ttl_cache: this.runTime() > 300_000,
       ...(this.reasoningEffort !== undefined && {
         reasoning_effort: this.reasoningEffort,
@@ -1681,9 +1680,17 @@ export abstract class BaseAgent implements IAgent {
       }),
     });
 
-    this.taskBreakdown = response.choices[0].message.content;
+    // The model may return null content (e.g. when it responds with tool calls
+    // instead of text). Guard against storing a literal null so that template
+    // strings don't render "null".
+    const breakdownContent = response.choices
+      .map((c) => c.message.content)
+      .filter((s): s is string => typeof s === "string" && s.trim().length > 0)
+      .join("\n\n");
+
+    this.taskBreakdown = breakdownContent || "";
     this.log(`task breakdown cost: ${response.usd_cost}`);
-    return this.taskBreakdown;
+    return this.taskBreakdown || undefined;
   }
 
   async compressMessages(messages: Message[]) {
@@ -1713,7 +1720,7 @@ export abstract class BaseAgent implements IAgent {
     3. Next Steps - what we're about to do next to continue the user's original request.
     4. Tasks remaining - what tasks are left from the initial task breakdown.
 
-    Our initial task breakdown: ${this.taskBreakdown}
+    ${this.taskBreakdown ? `Our initial task breakdown: ${this.taskBreakdown}` : ""}
 
     This summary will replace the older history. The latest agent interaction will remain verbatim:
 
@@ -1729,20 +1736,22 @@ export abstract class BaseAgent implements IAgent {
 
     const response = await this.createAgentCompletion({
       messages: compressMessagesPayload,
+      tool_choice: "none",
     });
 
-    const summaries = response.choices.map((c) => c.message.content);
+    const summaries = response.choices
+      .map((c) => c.message.content)
+      .filter((s): s is string => typeof s === "string" && s.trim().length > 0);
     this.summaries.push(...summaries);
 
     const startMessages = [
       {
         role: "user",
         content: `
-        Initial task breakdown:
-        ${this.taskBreakdown}
+        ${this.taskBreakdown ? `Initial task breakdown:\n        ${this.taskBreakdown}` : "(No task breakdown available — summarize what you know from context above)"}
 
         We have just compressed the conversation to save memory:
-        ${JSON.stringify(summaries)}
+        ${summaries.length > 0 ? JSON.stringify(summaries) : "(summary unavailable — please continue from the task breakdown above)"}
 
         Please continue the task from where we left off
         `,

package/src/agents/tools/startAgentTask.ts

@@ -152,7 +152,9 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<Star
   // Default filesystem synchronization ON unless the caller explicitly opts out
   // (syncFs: false) or is using a messageId-based web sync. This ensures spawned
   // subagents always appear in `knowhow agents list` and can be attached/tailed.
-  const useSyncFs = syncFs !== false && !messageId;
+  // If the caller explicitly passes syncFs: true, honor it even when a messageId
+  // is also provided (messageId handles remote sync; syncFs handles local fs sync).
+  const useSyncFs = syncFs === true ? true : (syncFs !== false && !messageId);
 
   // Use provided taskId if given, otherwise generate one from the prompt
   const taskId = providedTaskId ?? generateTaskId(prompt);
@@ -175,7 +177,8 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<Star
 
   if (messageId) {
     args.push("--message-id", messageId);
-  } else if (useSyncFs) {
+  }
+  if (useSyncFs) {
     args.push("--sync-fs");
   }
   // When syncRemote is requested, pass it through so the spawned agent pushes

package/src/auth/keyAuth.ts

@@ -81,7 +81,7 @@ export async function authenticateWithKey(
   }
 }
 
-/** Register an Ed25519 CLI-auth key using the JWT obtained by browser PKCE. */
+/** Register an Ed25519 identity; the backend derives its scope from the source JWT. */
 export async function registerPublicKey(
   jwt: string,
   publicKeyBase64: string,
@@ -109,7 +109,13 @@ export async function registerPublicKey(
 
 export function storeJwt(jwt: string): void {
   const directory = path.dirname(JWT_FILE_PATH);
-  fs.mkdirSync(directory, { recursive: true });
-  fs.writeFileSync(JWT_FILE_PATH, jwt, { mode: 0o600 });
-  fs.chmodSync(JWT_FILE_PATH, 0o600);
+  const temporaryPath = `${JWT_FILE_PATH}.${process.pid}.tmp`;
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.writeFileSync(temporaryPath, jwt, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporaryPath, JWT_FILE_PATH);
+    fs.chmodSync(JWT_FILE_PATH, 0o600);
+  } finally {
+    fs.rmSync(temporaryPath, { force: true });
+  }
 }

package/src/auth/registerIdentity.ts

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { getOrCreatePublicKey } from "./keyManager";
+import { registerPublicKey, exchangePublicKeyJwt, storeJwt } from "./keyAuth";
+import { getConfig, updateConfig } from "../config";
+
+export interface RegisterIdentityOptions {
+  /** Optional Ed25519 private-key path. Defaults to ~/.knowhow/keys/id_ed25519. */
+  identityPath?: string;
+  /** API base URL. Defaults to KNOWHOW_API_URL or the production public API. */
+  apiUrl?: string;
+}
+
+/** Decode an unverified JWT payload for local routing information only. */
+export function decodeJwtPayload(jwt: string): Record<string, unknown> {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) throw new Error("Invalid JWT format: expected 3 parts");
+  const base64 = (parts[1] ?? "").replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  try {
+    const payload: unknown = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new Error();
+    return payload as Record<string, unknown>;
+  } catch {
+    throw new Error("Invalid JWT payload: could not parse JSON");
+  }
+}
+
+export function extractOrgIdFromJwt(jwt: string): string {
+  const payload = decodeJwtPayload(jwt);
+  const orgId = payload["org"] ?? payload["orgId"] ?? payload["org_id"] ?? payload["organizationId"];
+  if (typeof orgId !== "string" || !orgId) {
+    throw new Error("JWT does not contain an organization claim (expected org, orgId, org_id, or organizationId)");
+  }
+  return orgId;
+}
+
+/**
+ * Register a CLI identity using the JWT already stored in the current project's
+ * .knowhow/.jwt, then replace that JWT with one obtained via key authentication.
+ * This is intentionally generic: authorization scope is derived by the backend
+ * from the verified source JWT.
+ */
+export async function registerIdentity(options: RegisterIdentityOptions = {}): Promise<void> {
+  const apiUrl = options.apiUrl ?? process.env.KNOWHOW_API_URL ?? "https://api.knowhow.tyvm.ai";
+  const jwtPath = path.join(process.cwd(), ".knowhow", ".jwt");
+  if (!fs.existsSync(jwtPath)) throw new Error(`JWT file not found: ${jwtPath}`);
+  const sourceJwt = fs.readFileSync(jwtPath, "utf8").trim();
+  if (!sourceJwt) throw new Error(`JWT file is empty: ${jwtPath}`);
+
+  const orgId = extractOrgIdFromJwt(sourceJwt);
+  const keyPair = getOrCreatePublicKey(options.identityPath);
+  await registerPublicKey(sourceJwt, keyPair.publicKeyBase64, apiUrl);
+  const identityJwt = await exchangePublicKeyJwt(orgId, apiUrl, options.identityPath);
+  storeJwt(identityJwt);
+
+  const config = await getConfig();
+  if (!config.modelProviders) config.modelProviders = [];
+  if (!config.modelProviders.some((provider: { provider: string }) => provider.provider === "knowhow")) {
+    config.modelProviders.push({ provider: "knowhow" });
+  }
+  config.orgId = orgId;
+  config.cliIdentityPath = path.resolve(options.identityPath ?? keyPair.privateKeyPath);
+  await updateConfig(config);
+
+  console.log(`✅ Identity registered. Identity: ${keyPair.fingerprint}, Org: ${orgId}`);
+}

package/src/chat/modules/AgentModule.ts

@@ -8,6 +8,7 @@ import {
   TaskRegistry,
   SyncedAgentWatcher,
   SyncerService,
+  AgentService,
 } from "../../services/index";
 import { AttachableAgent } from "../../services/SyncedAgentWatcher";
 import * as fs from "fs";
@@ -77,10 +78,15 @@ export class AgentModule extends BaseChatModule {
     | { toolCall?: string; toolUsed?: string; agentSay?: string; done: string }
     | undefined;
 
+  private agentService: AgentService;
+  private eventService: EventService;
+
   constructor() {
     super();
     this.taskRegistry = new TaskRegistry();
     this.sessionManager = new SessionManager();
+    this.agentService = services().Agents;
+    this.eventService = services().Events;
   }
 
   /**
@@ -327,7 +333,7 @@ export class AgentModule extends BaseChatModule {
     await super.initialize(service);
 
     // Set up plugin log event handler - use setListener so re-init doesn't double-subscribe
-    const Events = services().Events;
+    const Events = this.eventService;
     Events.setListener(
       { key: "agentModule:pluginLog", event: Events.eventTypes.pluginLog },
       (logEvent: any) => {
@@ -405,7 +411,7 @@ export class AgentModule extends BaseChatModule {
         // Set selected agent in context and enable agent mode
         if (context) {
           // Create a temporary agent instance to read its default model/provider
-          const agentContext = services().Agents.getAgentContext();
+          const agentContext = this.agentService.getAgentContext();
           const tempAgent = createAgent(
             agentName as AgentName,
             agentContext
@@ -427,6 +433,25 @@ export class AgentModule extends BaseChatModule {
           this.chatService.setMode("agent");
         }
 
+        console.log(
+          `Agent mode enabled. Selected agent: ${agentName}. Type your task to get started.`
+        );
+      } else if (this.agentService.listAgents().includes(agentName)) {
+        // Config agent from knowhow.json
+        if (context) {
+          const configAgent = this.agentService.getAgent<BaseAgent>(agentName);
+          context.selectedAgent = configAgent;
+          context.agentMode = true;
+          context.currentAgent = agentName;
+          const clientInfo = await configAgent.clientService.getClient(
+            undefined,
+            configAgent.getModel()
+          );
+          context.currentModel = clientInfo.model;
+          context.currentProvider = clientInfo.provider;
+
+          this.chatService.setMode("agent");
+        }
         console.log(
           `Agent mode enabled. Selected agent: ${agentName}. Type your task to get started.`
         );
@@ -601,12 +626,16 @@ export class AgentModule extends BaseChatModule {
    */
   async handleAgentsCommand(args: string[]): Promise<void> {
     try {
-      const agentNames = Object.keys(agentConstructors);
+      const builtinNames = Object.keys(agentConstructors);
+      const configAgentNames = this.agentService.listAgents();
+      // Merge, deduplicate, preserving built-ins first
+      const agentNames = [...new Set([...builtinNames, ...configAgentNames])];
 
       if (agentNames.length > 0) {
         console.log("\nAvailable agents:");
         agentNames.forEach((name) => {
-          console.log(`  - ${name}`);
+          const isConfig = !builtinNames.includes(name);
+          console.log(`  - ${name}${isConfig ? " (config)" : ""}`);
         });
         console.log("─".repeat(80), "\n");
 
@@ -700,11 +729,14 @@ export class AgentModule extends BaseChatModule {
       const agentName = session.agentName || context.currentAgent;
       const previousAgentMode = context?.agentMode;
 
-      if (!agentName || !agentConstructors[agentName as AgentName]) {
+      if (!agentName) {
         console.error(`Agent ${agentName} not found.`);
         return;
       }
 
+      // setupAgent resolves both built-in agents and custom ConfigAgents. Do
+      // not reject config-defined agents here before it gets that opportunity.
+
       // Start agent with Knowhow task context and restored message history
       const remoteTaskId = asRemoteTaskId(session.knowhowTaskId);
       const { agent, taskId } = await this.setupAgent({
@@ -817,7 +849,7 @@ export class AgentModule extends BaseChatModule {
     enabledTools?: string[];
   }) {
     const { input, chatHistory = [], agentName } = options;
-    const agentContext = services().Agents.getAgentContext();
+    const agentContext = this.agentService.getAgentContext();
 
     // Resolve agent: built-in agents first, then fall back to ConfigAgents from knowhow.json
     let agent: BaseAgent;
@@ -826,7 +858,7 @@ export class AgentModule extends BaseChatModule {
     } else {
       // Try to find a ConfigAgent registered via loadAgentsFromConfig (from knowhow.json agents[])
       try {
-        const configAgent = services().Agents.getAgent(options.agentName);
+        const configAgent = this.agentService.getAgent(options.agentName);
         agent = configAgent as unknown as BaseAgent;
       } catch {
         throw new Error(

package/src/clients/index.ts

@@ -544,14 +544,17 @@ export class AIClient {
       }
 
       // Handle the case when model prefix is gpt-5 and the provider is knowhow, and the actual model is openai/gpt-5
+      // Also handles deep prefixes like "accounts/fireworks/models/kimi-k3" matched by "kimi-k3"
       const inferredFound = models.find((m) => {
         const split = m.split("/");
         if (split.length < 2) return false;
         const inferredModel = split.slice(1).join("/");
+        const lastSegment = split[split.length - 1];
         return (
           m === modelPrefix ||
           inferredModel === modelPrefix ||
-          inferredModel.startsWith(modelPrefix)
+          inferredModel.startsWith(modelPrefix) ||
+          lastSegment === modelPrefix
         );
       });
       if (inferredFound) {
@@ -626,6 +629,36 @@ export class AIClient {
       return { provider, model };
     }
 
+    // When an explicit provider is given and the model contains slashes (e.g.
+    // provider="knowhow", model="anthropic/claude-sonnet-4-6"), check if the
+    // explicit provider has a model that matches by ignoring the leading
+    // provider prefix segments. Also handle deep prefixes like
+    // "accounts/fireworks/models/kimi-k3" → search for "kimi-k3".
+    if (provider && model) {
+      const providerModels = this.clientModels[provider] ?? [];
+      if (model.includes("/")) {
+        // Model has slashes: try progressively stripping leading prefix segments
+        const modelParts = model.split("/");
+        for (let i = 1; i < modelParts.length; i++) {
+          const suffix = modelParts.slice(i).join("/");
+          // Exact match within the explicit provider
+          if (this.providerHasModel(provider, suffix)) {
+            return { provider, model: suffix };
+          }
+        }
+      }
+      // For any model (with or without slashes): check if a registered model's
+      // last path segment matches the requested model name.
+      // e.g. provider="fireworks", model="kimi-k3" matches
+      //      "accounts/fireworks/models/kimi-k3"
+      const lastSegmentMatch = providerModels.find(
+        (m) => m.split("/").pop() === model
+      );
+      if (lastSegmentMatch) {
+        return { provider, model: lastSegmentMatch };
+      }
+    }
+
     // If an explicit provider was given, don't fall through to fuzzy cross-provider
     // search — that would silently pick a completely different provider (e.g. nvidia
     // instead of fireworks). Just pass through and let the API accept/reject the model.

package/src/commands/agent.ts

@@ -193,6 +193,7 @@ export function addAgentCommand(program: Command, getChatService: () => any): vo
 
         const { taskCompleted } = await agentModule.setupAgent({
           ...options,
+          agentName: options.agentName ?? config.chat?.defaultAgent ?? "Patcher",
           input,
           maxTimeLimit: parseInt(options.maxTimeLimit, 10),
           maxSpendLimit: parseFloat(options.maxSpendLimit),

package/src/commands/agents.ts

@@ -292,12 +292,15 @@ function buildRows(includeAll: boolean): Row[] {
  *   - A numeric index string ("1", "2", …) — 1-based row from `agents list`
  *   - An exact task ID
  *   - A partial task ID (substring match)
+ *
+ * NOTE: numeric index always uses the same row set as `agents list` (includeAll=false)
+ * so that index numbers are consistent across all subcommands.
  */
 function resolveTaskId(value: string, includeAll = false): string | null {
   const n = parseInt(value, 10);
   // Only treat as a numeric index if it's a small number (≤ 9999) — large numbers are timestamp-based task IDs
   if (!isNaN(n) && String(n) === value.trim() && n <= 9999) {
-    const rows = buildRows(includeAll);
+    const rows = buildRows(false);
     const row = rows[n - 1];
     return row ? row.taskId : null;
   }

package/src/commands/misc.ts

@@ -6,6 +6,7 @@ import { embed, upload, download, purge } from "../index";
 import { generate, buildWaves, normalizeInputPattern, GenerateOptions } from "../generate";
 import { init } from "../config";
 import { login } from "../login";
+import { registerIdentity } from "../auth/registerIdentity";
 import { KnowhowSimpleClient } from "../services/KnowhowClient";
 import { startChat } from "../chat";
 
@@ -24,8 +25,22 @@ export function addLoginCommand(program: Command): void {
     .description("Login to knowhow")
     .option("--jwt", "Use manual JWT input instead of browser login")
     .option("-i, --identity <path>", "Ed25519 private key to use for public-key login")
-    .action(async (options: { jwt?: boolean; identity?: string }) => {
-      await login(options.jwt, options.identity);
+    .option("--register-identity", "Register an Ed25519 identity using the JWT in .knowhow/.jwt")
+    .option("--api-url <url>", "API base URL override (falls back to KNOWHOW_API_URL env)")
+    .action(async (options: {
+      jwt?: boolean;
+      identity?: string;
+      registerIdentity?: boolean;
+      apiUrl?: string;
+    }) => {
+      if (options.registerIdentity) {
+        await registerIdentity({
+          identityPath: options.identity,
+          apiUrl: options.apiUrl,
+        });
+      } else {
+        await login(options.jwt, options.identity);
+      }
     });
 }
 

package/src/commands/processes.ts

@@ -8,8 +8,23 @@ import {
 import { runManagedProcessShim } from "../processes/managedProcessShim";
 
 const terminal = new Set(["exited", "failed", "stopped"]);
-function resolveProcess(value: string): ManagedProcess {
+function resolveProcess(value?: string, index?: string, options: any = {}): ManagedProcess {
   const root = getProcessesDir();
+  if (index !== undefined) {
+    const parsed = Number(index);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new Error(`Invalid process index '${index}'. Use the index shown by 'knowhow processes list'.`);
+    }
+    const items = filtered(options);
+    const item = items[parsed];
+    if (!item) {
+      throw new Error(`Managed process index ${parsed} not found. Run 'knowhow processes list${options.all ? " --all" : ""}' to see valid indices.`);
+    }
+    return new ManagedProcess(item.id, item.directory);
+  }
+  if (!value) {
+    throw new Error("Provide a process id, or use -i <index> from 'knowhow processes list'.");
+  }
   const matches = listManagedProcesses(root).filter((p) => p.id === value || p.id.includes(value));
   if (!matches.length) throw new Error(`Managed process not found: ${value}`);
   const exact = matches.find((p) => p.id === value);
@@ -30,13 +45,55 @@ function filtered(options: any): ManagedProcessInfo[] {
     return true;
   });
 }
+function truncate(value: string, width: number): string {
+  if (value.length <= width) return value;
+  if (width <= 1) return "…";
+  return `${value.slice(0, width - 1)}…`;
+}
+function truncateMiddle(value: string, width: number): string {
+  if (value.length <= width) return value;
+  if (width <= 1) return "…";
+  const left = Math.ceil((width - 1) / 2);
+  return `${value.slice(0, left)}…${value.slice(value.length - (width - left - 1))}`;
+}
+function printProcessTable(rows: Array<Record<string, string | number>>): void {
+  const terminalWidth = process.stdout.columns || 120;
+  const available = Math.max(80, Math.min(terminalWidth, 180));
+  const widths = {
+    index: Math.max(1, String(rows.length - 1).length),
+    state: Math.max(5, ...rows.map((row) => String(row.state).length)),
+    pid: Math.max(3, ...rows.map((row) => String(row.pid).length)),
+    background: 2,
+    id: Math.min(38, Math.max(12, ...rows.map((row) => String(row.id).length))),
+    parent: Math.min(20, Math.max(6, ...rows.map((row) => String(row.parent).length))),
+  };
+  const fixedWidth = widths.index + widths.state + widths.pid + widths.background
+    + widths.id + widths.parent + 12;
+  const commandWidth = Math.max(20, available - fixedWidth);
+  const header = ["#".padEnd(widths.index), "STATE".padEnd(widths.state),
+    "PID".padEnd(widths.pid), "BG".padEnd(widths.background),
+    "ID".padEnd(widths.id), "PARENT".padEnd(widths.parent), "COMMAND"];
+  console.log(header.join("  "));
+  console.log("─".repeat(Math.min(available, fixedWidth + commandWidth)));
+  for (const row of rows) {
+    console.log([
+      String(row.index).padEnd(widths.index),
+      String(row.state).padEnd(widths.state),
+      String(row.pid).padEnd(widths.pid),
+      String(row.background).padEnd(widths.background),
+      truncateMiddle(String(row.id), widths.id).padEnd(widths.id),
+      truncateMiddle(String(row.parent), widths.parent).padEnd(widths.parent),
+      truncate(String(row.command).replace(/\s+/g, " "), commandWidth),
+    ].join("  "));
+  }
+}
 function printList(options: any): void {
-  const rows = filtered(options).map(({ id, status }) => ({
-    id, state: status.state, pid: status.pid || "-", background: status.background ? "yes" : "no",
+  const rows = filtered(options).map(({ id, status }, index) => ({
+    index, id, state: status.state, pid: status.pid || "-", background: status.background ? "yes" : "no",
     parent: status.parentProcessId || "-", command: [status.command, ...status.args].join(" "),
   }));
   if (options.json) console.log(JSON.stringify(rows, null, 2));
-  else if (rows.length) console.table(rows);
+  else if (rows.length) printProcessTable(rows);
   else console.log("No managed processes.");
 }
 function addFilters(command: Command): Command {
@@ -71,6 +128,19 @@ async function followFiles(files: string[], fromEnd = true): Promise<void> {
   });
 }
 
+function parseMaxAge(value: string): number {
+  const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*([smhd]?)$/i);
+  if (!match) throw new Error(`Invalid max-age format: "${value}". Use e.g. 30m, 6h, 7d, 3600s.`);
+  const n = parseFloat(match[1]);
+  switch ((match[2] || "h").toLowerCase()) {
+    case "s": return n * 1000;
+    case "m": return n * 60 * 1000;
+    case "h": return n * 60 * 60 * 1000;
+    case "d": return n * 24 * 60 * 60 * 1000;
+    default: throw new Error(`Unknown unit in max-age: "${match[2]}"`);
+  }
+}
+
 export function addProcessesCommand(program: Command): void {
   const processes = addFilters(program.command("processes").description("inspect and control managed processes"));
   processes.action((rawOptions, command) => printList(commandOptions(rawOptions, command)));
@@ -80,11 +150,19 @@ export function addProcessesCommand(program: Command): void {
   processes.command("run").description("internal managed process shim").requiredOption("--config <path>")
     .action(async ({ config }) => runManagedProcessShim(path.resolve(config)));
 
-  processes.command("logs <id>").alias("tail").option("-n, --lines <number>", "lines to show", "100")
+  // Avoid Commander's built-in help exit here. The optional tracing module
+  // flushes asynchronously on process.exit, while Commander expects it never
+  // to return, which can otherwise produce a spurious "unknown option" error.
+  addFilters(processes.command("logs [id]").alias("tail"))
+    .helpOption(false)
+    .option("-h, --help", "display help for command")
+    .option("-i, --index <number>", "select by the zero-based index shown by processes list")
+    .option("-n, --lines <number>", "lines to show", "100")
     .option("-f, --follow", "follow output").option("--stderr", "show stderr instead of stdout")
     .option("--both", "show stdout and stderr").action(async (id, rawOptions, command) => {
       const options = commandOptions(rawOptions, command);
-      const managed = resolveProcess(id);
+      if (options.help) { command.outputHelp(); return; }
+      const managed = resolveProcess(id, options.index, options);
       const files = options.both ? [managed.stdoutPath, managed.stderrPath] : [options.stderr ? managed.stderrPath : managed.stdoutPath];
       for (const file of files) process.stdout.write(tailText(file, Math.max(0, Number(options.lines) || 100)));
       if (options.follow) await followFiles(files);
@@ -135,4 +213,36 @@ export function addProcessesCommand(program: Command): void {
     });
     render(null, "");
   });
+
+  processes.command("cleanup")
+    .description("remove process directories older than max-age (default 24h)")
+    .option("--max-age <duration>", "max age before removal, e.g. 30m, 6h, 7d (default: 24h)", "24h")
+    .option("--dry-run", "show what would be removed without deleting")
+    .action(async (rawOptions) => {
+      const options = typeof rawOptions?.optsWithGlobals === "function" ? rawOptions.optsWithGlobals() : rawOptions;
+      const maxAgeMs = parseMaxAge(options.maxAge || "24h");
+      const processesDir = getProcessesDir();
+      if (!fs.existsSync(processesDir)) { console.log("No processes directory found."); return; }
+      const entries = fs.readdirSync(processesDir, { withFileTypes: true });
+      const now = Date.now();
+      let removed = 0;
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const dirPath = path.join(processesDir, entry.name);
+        const statusPath = path.join(dirPath, "status.json");
+        if (!fs.existsSync(statusPath)) continue;
+        const stats = fs.statSync(dirPath);
+        const age = now - stats.mtimeMs;
+        if (age > maxAgeMs) {
+          if (options.dryRun) {
+            console.log(`[dry-run] would remove: ${entry.name} (age: ${Math.round(age / 60000)}m)`);
+          } else {
+            console.log(`🧹 Removing: ${entry.name} (age: ${Math.round(age / 60000)}m)`);
+            fs.rmSync(dirPath, { recursive: true, force: true });
+          }
+          removed++;
+        }
+      }
+      console.log(`${options.dryRun ? "[dry-run] " : ""}${removed} process director${removed === 1 ? "y" : "ies"} ${options.dryRun ? "would be" : ""} removed.`);
+    });
 }

package/src/hashes.ts

@@ -19,11 +19,13 @@ export async function getHashes() {
 /**
  * Atomically save hashes to disk — writes to a temp file then renames,
  * preventing concurrent writes from producing corrupted/truncated JSON.
+ * The hash directory is optional state and may not exist in a fresh checkout.
  */
 export async function saveHashes(hashes: any) {
   const target = ".knowhow/.hashes.json";
   const tmp = `${target}.tmp.${process.pid}`;
   try {
+    fs.mkdirSync(".knowhow", { recursive: true });
     fs.writeFileSync(tmp, JSON.stringify(hashes, null, 2));
     fs.renameSync(tmp, target);
   } catch (err) {

package/src/processes/ProcessManager.ts

@@ -34,8 +34,9 @@ export function listManagedProcesses(processesDir = getProcessesDir()): ManagedP
     .sort((a, b) => b.status.startedAt.localeCompare(a.status.startedAt));
 }
 function makeId(command: string): string {
+  const ts = Date.now();
   const name = path.basename(command).replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 28) || "process";
-  return `${name}-${Date.now()}-${randomBytes(3).toString("hex")}`;
+  return `${ts}-${name}-${randomBytes(3).toString("hex")}`;
 }
 function waitForFile(file: string, timeoutMs: number): Promise<void> {
   const started = Date.now();

package/src/processes/managedProcessShim.ts

@@ -70,12 +70,11 @@ export async function runManagedProcessShim(configPath: string): Promise<void> {
   fs.writeFileSync(path.join(dir, "pid"), child.pid ? `${child.pid}\n` : "");
   writeStatus();
 
-  let fifoFd: number | undefined;
   let fifoStream: fs.ReadStream | undefined;
   if (process.platform !== "win32") {
     // O_RDWR prevents transient writers disconnecting from delivering EOF to the shim.
-    fifoFd = fs.openSync(fifoPath, fs.constants.O_RDWR);
-    fifoStream = fs.createReadStream("", { fd: fifoFd, autoClose: false });
+    const fifoFd = fs.openSync(fifoPath, fs.constants.O_RDWR);
+    fifoStream = fs.createReadStream("", { fd: fifoFd, autoClose: true });
     fifoStream.on("data", (chunk) => {
       fs.appendFileSync(inputLogPath, chunk);
       if (child.stdin?.writable) child.stdin.write(chunk);
@@ -110,6 +109,19 @@ export async function runManagedProcessShim(configPath: string): Promise<void> {
     });
   });
   if (parentTimer) clearInterval(parentTimer);
-  fifoStream?.destroy();
-  if (fifoFd !== undefined) try { fs.closeSync(fifoFd); } catch {}
+  if (fifoStream && !fifoStream.closed) {
+    // A FIFO read cannot always be cancelled by closing its descriptor (notably
+    // on macOS). Wake the pending read before asking ReadStream to close it;
+    // otherwise each completed command can leave its shim wedged in close(2).
+    const wakeFd = fs.openSync(fifoPath, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK);
+    try {
+      fs.writeSync(wakeFd, Buffer.from([0]));
+    } finally {
+      fs.closeSync(wakeFd);
+    }
+    await new Promise<void>((resolve) => {
+      fifoStream!.once("close", resolve);
+      fifoStream!.destroy();
+    });
+  }
 }