@tyvm/knowhow 0.0.147 → 0.0.149

package/src/clients/http.ts

@@ -1,4 +1,4 @@
-import http from "../utils/http";
+import http, { HTTP_UNAUTHORIZED_HANDLER, RefreshableHeaders } from "../utils/http";
 import {
   GenericClient,
   CompletionOptions,
@@ -17,16 +17,72 @@ export interface HttpClientOptions {
   extra_body?: Record<string, any>;
 }
 
+/**
+ * Optional callback that, when set, is called whenever a 401 is received
+ * (reactive refresh) or whenever `needsRefresh()` returns true before a
+ * request (proactive refresh).  Override this in a subclass or set it
+ * directly on an instance:
+ *
+ *   client.refreshToken = async () => { const newJwt = await ...; client.setJwt(newJwt); };
+ */
+export type RefreshTokenFn = () => Promise<void>;
+
 export class HttpClient implements GenericClient {
   /** Timeout in milliseconds for HTTP requests. Default: 30000 (30s). Use 0 to disable. */
   private timeout: number;
-  private headers: Record<string, string>;
+  private headers: RefreshableHeaders;
   private extra_body: Record<string, any>;
   /** Optional pricing table: model id → per-million-token prices */
   private pricingMap: Record<string, ModelPricing> = {};
 
+  /**
+   * Override this to provide automatic token refresh.  Called reactively on
+   * 401 responses (via HTTP_UNAUTHORIZED_HANDLER) and proactively before
+   * each request when `needsRefresh()` returns true.
+   *
+   * The implementation should obtain a new token and call `this.setJwt()`
+   * (or `this.setKey()`) before returning.
+   */
+  refreshToken: RefreshTokenFn | undefined = undefined;
+
+  /**
+   * Override this to provide proactive expiry detection.  When it returns
+   * `true`, `refreshToken()` is called before the next outgoing request.
+   * The default implementation decodes the JWT `exp` claim (< 5 min window).
+   */
+  needsRefresh(): boolean {
+    const authHeader = (this.headers as Record<string, string>)["Authorization"];
+    if (!authHeader) return false;
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3) return false;
+      const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+      return typeof payload.exp === "number" && payload.exp * 1000 - Date.now() < 5 * 60 * 1000;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Call before each outgoing request to proactively refresh an expiring
+   * token.  No-ops when no `refreshToken` hook is set.
+   */
+  private async refreshIfNeeded(): Promise<void> {
+    if (this.refreshToken && this.needsRefresh()) {
+      await this.refreshToken();
+    }
+  }
+
   constructor(private baseUrl: string, options: HttpClientOptions = {}) {
     this.headers = options.headers ?? {};
+    // Wire the reactive 401 handler so the low-level http util can retry once
+    // after a token refresh without callers needing to do anything extra.
+    Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
+      enumerable: false,
+      configurable: true,
+      get: () => this.refreshToken ? () => this.refreshToken!() : undefined,
+    });
     this.timeout = options.timeout ?? 30000;
     this.extra_body = options.extra_body ?? {};
   }
@@ -69,10 +125,8 @@ export class HttpClient implements GenericClient {
   }
 
   setJwt(jwt: string) {
-    this.headers = {
-      ...this.headers,
-      Authorization: `Bearer ${jwt}`,
-    };
+    // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
+    this.headers.Authorization = `Bearer ${jwt}`;
   }
 
   setBaseUrl(baseUrl: string) {
@@ -163,7 +217,8 @@ export class HttpClient implements GenericClient {
     if (options.timeout !== undefined) this.timeout = options.timeout;
     if (options.extra_body !== undefined) this.extra_body = options.extra_body;
     if (options.headers) {
-      this.headers = { ...this.headers, ...options.headers };
+      // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
+      Object.assign(this.headers, options.headers);
     }
   }
 
@@ -183,6 +238,7 @@ export class HttpClient implements GenericClient {
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const body = {
         ...options,
@@ -232,6 +288,7 @@ export class HttpClient implements GenericClient {
   async *createChatCompletionStream(
     options: CompletionOptions
   ): AsyncGenerator<StreamChunk> {
+    await this.refreshIfNeeded();
     const body = {
       ...options,
       model: options.model,
@@ -316,6 +373,7 @@ export class HttpClient implements GenericClient {
     options: CompletionOptions,
     store = false
   ): Promise<CompletionResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       // Extract system messages as instructions
       const systemMessages = options.messages.filter((m) => m.role === "system");
@@ -484,6 +542,7 @@ export class HttpClient implements GenericClient {
   }
 
   async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const response = await http.post(
         `${this.baseUrl}/v1/embeddings`,
@@ -511,6 +570,7 @@ export class HttpClient implements GenericClient {
   }
 
   async getModels(type = "all") {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const response = await http.get(`${this.baseUrl}/v1/models?type=${type}`, {
         headers: this.headers as Record<string, string>,

package/src/clients/index.ts

@@ -528,12 +528,14 @@ export class AIClient {
   }
 
   providerHasModel(provider: string, model: string): boolean {
+    if (!provider) return false;
     const models = this.clientModels[provider];
     if (!models) return false;
     return models.includes(model);
   }
 
   findModel(modelPrefix: string) {
+    if (!modelPrefix) return undefined;
     for (const provider of Object.keys(this.clientModels)) {
       const models = this.clientModels[provider] as string[];
       const foundModel = models.find((m) => m.startsWith(modelPrefix));
@@ -542,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) {
@@ -624,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

@@ -35,6 +35,18 @@ import { getConfig } from "../config";
 const AGENTS_DIR = path.join(".knowhow", "processes", "agents");
 const SESSIONS_DIR = path.join(".knowhow", "chats", "sessions");
 
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "error",
+  "done",
+]);
+const ACTIVE_STATUSES = new Set(["running", "paused"]);
+// Older task records did not persist a pid. After this grace period, report
+// them as unverifiable rather than continuing to claim they are running.
+const UNVERIFIED_TASK_GRACE_MS = 5 * 60 * 1000;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -68,11 +80,42 @@ function loadStatus(taskId: string): string {
   }
 }
 
-/** Get the canonical status — meta.status is live/preferred; status.txt is fallback */
-function getStatus(taskId: string, meta: any | null): string {
-  if (meta?.status) return meta.status;
-  const fromFile = loadStatus(taskId);
-  return fromFile ?? "unknown";
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error: any) {
+    // EPERM means the process exists but cannot be signalled by this user.
+    return error?.code === "EPERM";
+  }
+}
+
+/**
+ * Get the effective status, reconciling persisted state with process liveness.
+ * An agent can be terminated before AgentSyncFs gets a chance to finalize its
+ * files; those records must not remain "running" forever.
+ */
+export function getStatus(taskId: string, meta: any | null): string {
+  const persisted = meta?.status || loadStatus(taskId) || "unknown";
+  if (TERMINAL_STATUSES.has(persisted)) return persisted;
+  if (meta?.inProgress === false) return "completed";
+  if (!ACTIVE_STATUSES.has(persisted)) return persisted;
+
+  const pid = meta?.pid ?? meta?.processId;
+  if (typeof pid === "number") {
+    return pidAlive(pid) ? persisted : "failed";
+  }
+
+  const lastKnownTime = meta?.lastUpdate ?? meta?.startTime;
+  const lastKnownMs = lastKnownTime ? new Date(lastKnownTime).getTime() : NaN;
+  if (
+    !Number.isFinite(lastKnownMs) ||
+    Date.now() - lastKnownMs > UNVERIFIED_TASK_GRACE_MS
+  ) {
+    return "stale";
+  }
+
+  return persisted;
 }
 
 function elapsedStr(startIso: string | undefined, endIso?: string): string {
@@ -203,9 +246,9 @@ function buildRows(includeAll: boolean): Row[] {
 
   for (const taskId of taskIds) {
     const meta = loadMeta(taskId);
-    const status = meta?.status ?? loadStatus(taskId);
+    const status = getStatus(taskId, meta);
 
-    if (!includeAll && (status === "completed" || status === "killed")) {
+    if (!includeAll && (TERMINAL_STATUSES.has(status) || status === "stale")) {
       const lastUpdate = meta?.lastUpdate ?? "";
       if (lastUpdate) {
         const age = Date.now() - new Date(lastUpdate).getTime();
@@ -221,7 +264,9 @@ function buildRows(includeAll: boolean): Row[] {
         : "";
     const elapsed = elapsedStr(
       meta?.startTime,
-      meta?.status === "completed" ? meta?.lastUpdate : undefined
+      TERMINAL_STATUSES.has(status) || status === "stale"
+        ? meta?.lastUpdate
+        : undefined
     );
     const lastUpdate = meta?.lastUpdate
       ? new Date(meta.lastUpdate).toLocaleString()
@@ -247,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

@@ -0,0 +1,203 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getProcessesDir, listManagedProcesses, ManagedProcess,
+  ManagedProcessInfo, processDirectory,
+} from "../processes/ProcessManager";
+import { runManagedProcessShim } from "../processes/managedProcessShim";
+
+const terminal = new Set(["exited", "failed", "stopped"]);
+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);
+  if (!exact && matches.length > 1) throw new Error(`Ambiguous process id '${value}': ${matches.map((p) => p.id).join(", ")}`);
+  const item = exact || matches[0];
+  return new ManagedProcess(item.id, item.directory);
+}
+function commandOptions(options: any, command?: Command): any {
+  const fromOptions = typeof options?.optsWithGlobals === "function" ? options.optsWithGlobals() : options || {};
+  const fromCommand = typeof command?.optsWithGlobals === "function" ? command.optsWithGlobals() : {};
+  return { ...fromOptions, ...fromCommand };
+}
+function filtered(options: any): ManagedProcessInfo[] {
+  return listManagedProcesses().filter((item) => {
+    if (!options.all && terminal.has(item.status.state)) return false;
+    if (options.parent && item.status.parentProcessId !== options.parent) return false;
+    if (options.background !== undefined && item.status.background !== options.background) return false;
+    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 }, 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) printProcessTable(rows);
+  else console.log("No managed processes.");
+}
+function addFilters(command: Command): Command {
+  return command.option("-a, --all", "include completed processes")
+    .option("--parent <id>", "filter by parent process/task id")
+    .option("--background", "show only background processes")
+    .option("--json", "emit JSON");
+}
+function tailText(file: string, lines: number): string {
+  if (!fs.existsSync(file)) return "";
+  return fs.readFileSync(file, "utf8").split("\n").slice(-lines - 1).join("\n");
+}
+async function followFiles(files: string[], fromEnd = true): Promise<void> {
+  const offsets = new Map<string, number>();
+  for (const file of files) offsets.set(file, fromEnd && fs.existsSync(file) ? fs.statSync(file).size : 0);
+  await new Promise<void>((resolve) => {
+    const poll = setInterval(() => {
+      for (const file of files) {
+        if (!fs.existsSync(file)) continue;
+        const size = fs.statSync(file).size; const offset = offsets.get(file) || 0;
+        if (size < offset) offsets.set(file, 0);
+        if (size > (offsets.get(file) || 0)) {
+          const start = offsets.get(file) || 0;
+          const fd = fs.openSync(file, "r"); const data = Buffer.alloc(size - start);
+          fs.readSync(fd, data, 0, data.length, start); fs.closeSync(fd);
+          process.stdout.write(data); offsets.set(file, size);
+        }
+      }
+    }, 150);
+    const done = () => { clearInterval(poll); resolve(); };
+    process.once("SIGINT", done); process.once("SIGTERM", done);
+  });
+}
+
+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)));
+  addFilters(processes.command("list").description("list managed processes"))
+    .action((rawOptions, command) => printList(commandOptions(rawOptions, command)));
+
+  processes.command("run").description("internal managed process shim").requiredOption("--config <path>")
+    .action(async ({ config }) => runManagedProcessShim(path.resolve(config)));
+
+  // 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);
+      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);
+    });
+
+  processes.command("send <id> [input...]").option("-n, --no-newline", "do not append newline")
+    .action(async (id, input: string[], rawOptions, command) => {
+      const options = commandOptions(rawOptions, command);
+      const managed = resolveProcess(id);
+      await managed.write((input || []).join(" ") + (options.newline ? "\n" : ""));
+    });
+
+  processes.command("signal <id> [signal]").action((id, signal = "SIGTERM") => resolveProcess(id).signal(signal.toUpperCase() as NodeJS.Signals));
+  processes.command("stop <id>").action((id) => resolveProcess(id).signal("SIGTERM"));
+  processes.command("kill <id>").action((id) => resolveProcess(id).signal("SIGKILL"));
+
+  processes.command("attach <id>").description("attach terminal (Ctrl-] to detach)").action(async (id) => {
+    const managed = resolveProcess(id); let detached = false;
+    const raw = !!process.stdin.isTTY; if (raw) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const onData = async (data: Buffer) => {
+      if (data.includes(0x1d)) { detached = true; return; }
+      try { await managed.write(data.toString()); } catch (error) { console.error(String(error)); detached = true; }
+    };
+    process.stdin.on("data", onData);
+    const offsets = [managed.stdoutPath, managed.stderrPath].map((f) => fs.existsSync(f) ? fs.statSync(f).size : 0);
+    await new Promise<void>((resolve) => {
+      const timer = setInterval(() => {
+        [managed.stdoutPath, managed.stderrPath].forEach((file, i) => {
+          if (!fs.existsSync(file)) return; const size = fs.statSync(file).size;
+          if (size > offsets[i]) { const fd = fs.openSync(file, "r"); const b = Buffer.alloc(size - offsets[i]); fs.readSync(fd, b, 0, b.length, offsets[i]); fs.closeSync(fd); process.stdout.write(b); offsets[i] = size; }
+        });
+        if (detached || terminal.has(managed.status.state)) { clearInterval(timer); resolve(); }
+      }, 100);
+    });
+    process.stdin.off("data", onData); process.stdin.pause(); if (raw) process.stdin.setRawMode(false);
+  });
+
+  processes.command("tree").option("-a, --all", "include completed processes").action((rawOptions, command) => {
+    const options = commandOptions(rawOptions, command);
+    const items = listManagedProcesses().filter((p) => options.all || !terminal.has(p.status.state));
+    const ids = new Set(items.map((p) => p.id));
+    const children = new Map<string | null, ManagedProcessInfo[]>();
+    for (const item of items) { const parent = item.status.parentProcessId && ids.has(item.status.parentProcessId) ? item.status.parentProcessId : null; children.set(parent, [...(children.get(parent) || []), item]); }
+    const render = (parent: string | null, prefix: string) => (children.get(parent) || []).forEach((item, index, array) => {
+      const last = index === array.length - 1; console.log(`${prefix}${last ? "└─" : "├─"}${item.id} [${item.status.state}] ${item.status.command}`);
+      render(item.id, prefix + (last ? "  " : "│ "));
+    });
+    render(null, "");
+  });
+}

package/src/commands/services.ts

@@ -3,7 +3,8 @@ import * as allTools from "../agents/tools";
 import { LazyToolsService, services, MinimalToolsService, TracingService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
-import { getConfig } from "../config";
+import { getConfig, getConfigSync } from "../config";
+import { authenticateWithKey } from "../auth/keyAuth";
 
 /**
  * Shared service setup used by commands that need full services (chat, agent, worker, etc.)
@@ -20,6 +21,7 @@ export async function setupServices() {
     MediaProcessor,
     Behaviors,
     RuntimeReload,
+    Extensions,
   } = services();
 
   await Plugins.refreshConfiguredState();
@@ -76,6 +78,25 @@ export async function setupServices() {
       `⚠ Some MCP servers failed to connect (continuing without them): ${msg}`
     );
   }
+  // Attempt silent JWT refresh via SSH identity before registering models.
+  // This handles the case where the JWT has expired but the user has a valid
+  // SSH identity registered — they shouldn't need to run `knowhow login` again
+  // unless they want to switch organizations.
+  try {
+    const startupConfig = getConfigSync();
+    if (startupConfig.orgId && !process.env.KNOWHOW_JWT) {
+      await authenticateWithKey(
+        startupConfig.orgId,
+        process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai",
+        startupConfig.cliIdentityPath
+      );
+    }
+  } catch (_err) {
+    // Non-fatal: if SSH refresh fails (no key, revoked, network issue), we
+    // continue with the existing JWT (or no JWT). The user will see model
+    // warnings if no valid JWT is available.
+  }
+
   console.log("Connecting to clients...");
   await Clients.registerConfiguredModels();
   console.log("✓ Services are set up and ready to go!");
@@ -92,6 +113,7 @@ export async function setupServices() {
     Behaviors,
     Events,
     Tracing: TracingService,
+    Extensions,
   };
 
   // Call destroy() on all modules when the process is shutting down so they

package/src/index.ts

@@ -65,6 +65,7 @@ export * as embeddings from "./embeddings";
 export * as types from "./types";
 export * as processors from "./processors";
 export * as ai from "./ai";
+export * from "./processes/ProcessManager";
 
 // Export module system types for external modules
 export * from "./services/modules/types";