@tyvm/knowhow 0.0.145 → 0.0.147

package/src/services/AgentSyncFs.ts

@@ -3,6 +3,7 @@
  * Handles synchronization via filesystem files in .knowhow/processes/agents/taskId/
  */
 import { BaseAgent } from "../agents/base/base";
+import { TraceAll } from "../util/Trace";
 import { promises as fs } from "fs";
 import * as path from "path";
 import { watch } from "fs";
@@ -19,6 +20,7 @@ export interface FsSyncOptions {
  * AgentSyncFs handles filesystem-based synchronization for agent tasks
  * Creates files in .knowhow/processes/agents/{taskId}/ for status and input
  */
+@TraceAll()
 export class AgentSyncFs {
   /** Shared cleanup interval across all instances to avoid duplicate cleanup runs */
   private static sharedCleanupInterval: NodeJS.Timeout | null = null;
@@ -128,6 +130,66 @@ export class AgentSyncFs {
     }
   }
 
+  /**
+   * Persist the remote identity alongside the local task. Keeping the local
+   * slug and remote UUID as separate fields lets resume reconnect without ever
+   * mistaking one for the other.
+   */
+  static async persistRemoteIdentity(
+    taskId: string,
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    const taskPath = path.join(AgentSyncFs.sharedBasePath, taskId);
+    await AgentSyncFs.writeRemoteIdentity(
+      taskPath,
+      remoteTaskId,
+      remoteMessageId
+    );
+  }
+
+  async setRemoteIdentity(
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    if (!this.taskPath) return;
+    await AgentSyncFs.writeRemoteIdentity(this.taskPath, remoteTaskId, remoteMessageId);
+  }
+
+  private static async writeRemoteIdentity(
+    taskPath: string,
+    remoteTaskId: string,
+    remoteMessageId?: string
+  ): Promise<void> {
+    try {
+      const metadataPath = path.join(taskPath, "metadata.json");
+      let metadata: any = {};
+      try {
+        metadata = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+      } catch {
+        // The normal path already created metadata, but recover if it was
+        // removed or malformed while the task was running.
+      }
+
+      metadata.remoteTaskId = remoteTaskId;
+      // Preserve the established session field name for compatibility with
+      // callers that already read knowhowTaskId.
+      metadata.knowhowTaskId = remoteTaskId;
+      if (remoteMessageId) {
+        metadata.remoteMessageId = remoteMessageId;
+        metadata.knowhowMessageId = remoteMessageId;
+      }
+
+      await fs.writeFile(
+        metadataPath,
+        JSON.stringify(metadata, null, 2),
+        "utf8"
+      );
+    } catch (error) {
+      console.error(`❌ Failed to persist remote task identity:`, error);
+    }
+  }
+
   /**
    * Append a token usage entry (including the full message chain sent for
    * that call) to usage.json. This is intended for debugging cache-hit
@@ -217,6 +279,9 @@ export class AgentSyncFs {
       // thread messages via `_reasoning_details` / `reasoning_summary`.)
       metadata.reasoningEffort = agent.getReasoningEffort?.();
       metadata.summarizeReasoning = agent.getSummarizeReasoning?.();
+      // Tool schemas are part of the provider cache prefix. Preserve the exact
+      // request-visible list so resume/fork can recreate the same request.
+      metadata.enabledTools = agent.getEnabledToolNames();
       metadata.inProgress = inProgress;
       metadata.lastUpdate = new Date().toISOString();
 

package/src/services/AgentSyncKnowhowWeb.ts

@@ -10,6 +10,7 @@ import {
 } from "./KnowhowClient";
 import { BaseAgent } from "../agents/base/base";
 import { wait } from "../utils";
+import { TraceAll } from "../util/Trace";
 
 export interface SyncOptions {
   messageId?: string;
@@ -27,6 +28,7 @@ export interface TaskSyncState {
  * AgentSynchronization handles all communication with the Knowhow API
  * for task creation, updates, status polling, and message synchronization
  */
+@TraceAll()
 export class AgentSyncKnowhowWeb {
   private client: KnowhowSimpleClient;
   private baseUrl: string;
@@ -36,6 +38,7 @@ export class AgentSyncKnowhowWeb {
   private agent: BaseAgent | undefined;
   private threadUpdateHandler: ((...args: any[]) => void) | undefined;
   private doneHandler: ((...args: any[]) => void) | undefined;
+  private syncErrorLogged = false;
   /**
    * Tracks the most recent in-flight thread update API call.
    * The done handler awaits this before sending the finalization call,
@@ -48,6 +51,17 @@ export class AgentSyncKnowhowWeb {
     this.client = new KnowhowSimpleClient(baseUrl);
   }
 
+  /**
+   * Remote outages can make both the update and pending-message requests fail
+   * on every thread event. Report the first failure for this task, then stay
+   * quiet so an unavailable optional sync service does not flood the chat.
+   */
+  private reportSyncErrorOnce(message: string, error: unknown): void {
+    if (this.syncErrorLogged) return;
+    this.syncErrorLogged = true;
+    console.error(message, error);
+  }
+
   /**
    * Create a new chat task in Knowhow
    */
@@ -68,7 +82,7 @@ export class AgentSyncKnowhowWeb {
       console.log(`✅ Created Knowhow chat task: ${knowhowTaskId}`);
       return knowhowTaskId;
     } catch (error) {
-      console.error(`❌ Failed to create Knowhow chat task:`, error);
+      this.reportSyncErrorOnce(`❌ Failed to create Knowhow chat task:`, error);
       return undefined;
     }
   }
@@ -95,7 +109,7 @@ export class AgentSyncKnowhowWeb {
       });
       console.log(`✅ Updated Knowhow chat task: ${knowhowTaskId}`);
     } catch (error) {
-      console.error(`❌ Failed to update Knowhow chat task:`, error);
+      this.reportSyncErrorOnce(`❌ Failed to update Knowhow chat task:`, error);
     }
   }
 
@@ -167,7 +181,10 @@ export class AgentSyncKnowhowWeb {
       await this.client.markMessagesAsProcessed(knowhowTaskId, messageIds);
       console.log(`✅ Marked ${messageIds.length} message(s) as processed`);
     } catch (error) {
-      console.error(`❌ Error checking/processing pending messages:`, error);
+      this.reportSyncErrorOnce(
+        `❌ Error checking/processing pending messages:`,
+        error
+      );
       // Continue execution even if synchronization fails
     }
   }
@@ -226,7 +243,7 @@ export class AgentSyncKnowhowWeb {
         }
         // Still paused, continue waiting
       } catch (error) {
-        console.error(`❌ Error polling task status:`, error);
+        this.reportSyncErrorOnce(`❌ Error polling task status:`, error);
         // Continue polling even on errors
       }
     }
@@ -350,6 +367,7 @@ export class AgentSyncKnowhowWeb {
     this.eventHandlersSetup = false;
     this.finalizationPromise = null;
     this.pendingThreadUpdatePromise = null;
+    this.syncErrorLogged = false;
   }
 
   /**

package/src/services/BehaviorsService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { KnowhowSimpleClient } from "./KnowhowClient";
 import { createHash } from "crypto";
 import { getConfig } from "../config";
+import { TraceAll } from "../util/Trace";
 
 const BEHAVIORS_DIR = ".knowhow/behaviors";
 const LOCAL_SKILLS_DIRS = [".agents/skills", ".knowhow/skills"];
@@ -30,6 +31,7 @@ export interface Behavior {
  * In-memory singleton for behaviors/skills.
  * Call initFromDisk() once at startup; tools then read from memory.
  */
+@TraceAll()
 export class BehaviorsService {
   private behaviors: Behavior[] = [];
   private skills: Behavior[] = [];

package/src/services/DockerService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { Config } from "../types";
 import { updateConfig } from "../config";
 import * as crypto from "crypto";
+import { TraceAll } from "../util/Trace";
 
 export interface DockerWorkerOptions {
   workspaceDir: string;
@@ -14,6 +15,7 @@ export interface DockerWorkerOptions {
   unshare?: boolean;
 }
 
+@TraceAll()
 export class DockerService {
   private static readonly IMAGE_NAME = "knowhow-worker";
   private static readonly CONTAINER_PREFIX = "knowhow-worker";

package/src/services/EmbeddingService.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { TraceAll } from "../util/Trace";
 import { globSync } from "glob";
 
 import {
@@ -38,6 +39,7 @@ interface EmbeddingServiceContext {
   plugins: PluginService;
 }
 
+@TraceAll()
 export class EmbeddingService {
   private config: Config;
   private embeddingClient: GenericClient;

package/src/services/EmbeddingsService.ts

@@ -20,6 +20,9 @@ export interface EmbeddingsResolver {
  * Modules can register a resolver for a given remoteType (e.g. "github", "s3")
  * via registerResolver(), and the core upload()/download() functions delegate to it.
  */
+import { TraceAll } from "../util/Trace";
+
+@TraceAll()
 export class EmbeddingsService {
   private resolvers = new Map<string, EmbeddingsResolver>();
 

package/src/services/KnowhowClient.ts

@@ -1,6 +1,10 @@
 import { createHash } from "crypto";
-import http from "../utils/http";
+import { TraceAll } from "../util/Trace";
+import http, { HTTP_UNAUTHORIZED_HANDLER, RefreshableHeaders } from "../utils/http";
 import fs from "fs";
+import { getConfigSync } from "../config";
+import { exchangePublicKeyJwt, storeJwt } from "../auth/keyAuth";
+import { keyPairExists } from "../auth/keyManager";
 import { Message } from "../clients/types";
 import path from "path";
 import {
@@ -141,17 +145,32 @@ export function loadKnowhowJwt(): string {
 export const KNOWHOW_API_URL =
   process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai";
 
+@TraceAll()
 export class KnowhowSimpleClient {
-  headers: Record<string, string> = {};
+  headers: RefreshableHeaders = {};
   jwtValidated = false;
+  private readonly canRefreshJwt: boolean;
+  private refreshPromise?: Promise<void>;
 
   constructor(
     private baseUrl = KNOWHOW_API_URL,
-    private jwt = loadKnowhowJwt()
+    jwt?: string
   ) {
-    this.setJwt(jwt);
+    // Explicit tokens (including KNOWHOW_JWT worker credentials) have no
+    // corresponding local identity and must never trigger interactive renewal.
+    this.canRefreshJwt = jwt === undefined && !process.env.KNOWHOW_JWT;
+    this.jwt = jwt ?? loadKnowhowJwt();
+    this.setJwt(this.jwt);
+    if (this.canRefreshJwt) {
+      Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
+        enumerable: false,
+        value: () => this.renewJwt(true),
+      });
+    }
   }
 
+  private jwt: string;
+
   /**
    * Reload the JWT from disk (useful after login refreshes the token).
    */
@@ -165,9 +184,45 @@ export class KnowhowSimpleClient {
 
   setJwt(jwt: string) {
     this.jwt = jwt;
-    this.headers = {
-      Authorization: `Bearer ${this.jwt}`,
-    };
+    // Keep this object stable: the HTTP wrapper retries with the same reference.
+    this.headers.Authorization = `Bearer ${this.jwt}`;
+  }
+
+  private jwtExpiresSoon(): boolean {
+    try {
+      const payload = JSON.parse(Buffer.from(this.jwt.split(".")[1], "base64url").toString("utf8"));
+      return typeof payload.exp === "number" && payload.exp * 1000 - Date.now() < 5 * 60 * 1000;
+    } catch {
+      return false;
+    }
+  }
+
+  private async renewJwt(force = false): Promise<void> {
+    if (!this.canRefreshJwt) return;
+    if (!force && !this.jwtExpiresSoon()) return;
+    if (this.refreshPromise) return this.refreshPromise;
+
+    this.refreshPromise = (async () => {
+      const config = getConfigSync();
+      const identityPath = config.cliIdentityPath;
+      if (!config.orgId || !keyPairExists(identityPath)) {
+        throw new Error("JWT expired and the CLI identity is unavailable. Please run `knowhow login` again.");
+      }
+      try {
+        const freshJwt = await exchangePublicKeyJwt(config.orgId, this.baseUrl, identityPath);
+        storeJwt(freshJwt);
+        this.setJwt(freshJwt);
+        this.jwtValidated = true;
+      } catch (error) {
+        throw new Error(
+          "Unable to renew the CLI session; the identity may have been revoked. Please run `knowhow login` again.",
+          { cause: error }
+        );
+      }
+    })().finally(() => {
+      this.refreshPromise = undefined;
+    });
+    return this.refreshPromise;
   }
 
   async checkJwt() {
@@ -175,6 +230,8 @@ export class KnowhowSimpleClient {
       throw new Error("No JWT found. Please login first.");
     }
 
+    await this.renewJwt();
+
     if (!this.jwtValidated) {
       try {
         this.jwtValidated = true;
@@ -186,6 +243,10 @@ export class KnowhowSimpleClient {
           return org.organizationId === orgId;
         });
       } catch (error) {
+        this.jwtValidated = false;
+        if (error instanceof Error && error.message.includes("renew the CLI session")) {
+          throw error;
+        }
         throw new Error("Invalid JWT. Please login again.");
       }
     }

package/src/services/LazyToolsService.ts

@@ -1,4 +1,5 @@
 import { minimatch } from "minimatch";
+import { TraceAll } from "../util/Trace";
 import { ToolsService, ToolContext, ToolCallContext } from "./Tools";
 import { Tool } from "../clients/types";
 import { ToolCall } from "../clients/types";
@@ -21,6 +22,7 @@ import { definitions } from "../agents/tools/lazy/definitions";
  * In web sessions where you get a new ToolService each interaction, then the cache busting is going to happen with each enable
  *
  */
+@TraceAll()
 export class LazyToolsService extends ToolsService {
   private allTools: Tool[] = [];
   // Start with lazy tools enabled by default
@@ -80,6 +82,13 @@ export class LazyToolsService extends ToolsService {
     return this.tools; // Returns filtered subset
   }
 
+  /** Rebuild the lazy catalog while preserving enable/disable preferences. */
+  resetTools(): void {
+    this.allTools = [];
+    super.resetTools();
+    this.registerLazyTools();
+  }
+
   // Enable tools matching glob patterns
   enableTools(patterns: string[]) {
     for (const pattern of patterns) {
@@ -97,6 +106,13 @@ export class LazyToolsService extends ToolsService {
     };
   }
 
+  /** Replace glob state with an exact persisted request-visible tool list. */
+  restoreEnabledTools(names: string[]): void {
+    this.enabledPatterns = [...new Set(names)];
+    this.disabledPatterns = [];
+    this.updateVisibleTools();
+  }
+
   // Disable tools matching glob patterns
   disableTools(patterns: string[]) {
     for (const pattern of patterns) {

package/src/services/Mcp.ts

@@ -6,6 +6,7 @@ import fs from "fs";
 import { McpConfig } from "../types";
 import { Tool } from "../clients";
 import { getConfig } from "../config";
+import { TraceAll } from "../util/Trace";
 import { ToolsService } from "./Tools";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -36,6 +37,7 @@ export * from "./McpWebsocketTransport";
  * Each of the tools are namespaced with a prefix: mcp_index_servername_toolName
  * This services handles calls made to the namespaced function name, and finds the proper client to call the tool on.
  */
+@TraceAll()
 export class McpService {
   connected = [];
   transports: Transport[] = [];
@@ -388,8 +390,15 @@ export class McpService {
   }
 
   async closeAll() {
-    await this.closeTransports();
-    await this.closeClients();
+    await Promise.allSettled([this.closeTransports()]);
+    await Promise.allSettled([this.closeClients()]);
+    // Connections are recreated from freshly-read configuration after reload.
+    this.clients = [];
+    this.transports = [];
+    this.connected = [];
+    this.config = [];
+    this.tools = [];
+    this.toolAliases = {};
   }
 
   getClientIndex(clientName: string) {

package/src/services/McpServer.ts

@@ -6,9 +6,11 @@ import { Tool, ToolProp } from "../clients/types";
 import { ToolsService } from "./Tools";
 import { MCPWebSocketTransport } from "./McpWebsocketTransport";
 import { WebSocket } from "ws";
+import { TraceAll } from "../util/Trace";
 
 export type McpServerConfig = { name: string; version: string };
 
+@TraceAll()
 export class McpServerService {
   server: McpServer | null = null;
   constructor(private toolsService: ToolsService) {}

package/src/services/MessageProcessor.ts

@@ -1,4 +1,5 @@
 import { Message } from "../clients/types";
+import { TraceAll } from "../util/Trace";
 
 export type ProcessorLifecycle =
   | "initial_call"
@@ -17,6 +18,7 @@ export interface ProcessorRegistration {
   priority: number;
 }
 
+@TraceAll()
 export class MessageProcessor {
   private processors: Map<ProcessorLifecycle, ProcessorRegistration[]> =
     new Map();

package/src/services/MinimalToolsService.ts

@@ -5,6 +5,7 @@ import { inspectTools } from "../agents/tools/minimal/inspectTools";
 import { minimalDefinitions } from "../agents/tools/minimal/definitions";
 import { finalAnswer } from "../agents/tools/finalAnswer";
 import { includedTools } from "../agents/tools/list";
+import { TraceAll } from "../util/Trace";
 
 /*
  * MinimalToolsService
@@ -19,6 +20,7 @@ import { includedTools } from "../agents/tools/list";
  * - Works on all providers and older models (no provider-specific defer_loading needed).
  * - Agents discover tools via inspectTools() and call them via callTool().
  */
+@TraceAll()
 export class MinimalToolsService extends ToolsService {
   /** Full catalog of every registered tool (base + extended). */
   private allToolsCatalog: Tool[] = [];

package/src/services/RuntimeReloadService.ts

@@ -0,0 +1,31 @@
+export interface RuntimeReloadResult {
+  tools: number;
+  mcps: number;
+  modules: number;
+}
+
+/** Coordinates in-place runtime refreshes and coalesces concurrent requests. */
+export class RuntimeReloadService {
+  private handler?: () => Promise<RuntimeReloadResult>;
+  private pending?: Promise<RuntimeReloadResult>;
+
+  configure(handler: () => Promise<RuntimeReloadResult>): void {
+    this.handler = handler;
+  }
+
+  isConfigured(): boolean {
+    return !!this.handler;
+  }
+
+  reload(): Promise<RuntimeReloadResult> {
+    if (!this.handler) {
+      return Promise.reject(new Error("Runtime reload is unavailable for this command"));
+    }
+    if (!this.pending) {
+      this.pending = this.handler().finally(() => {
+        this.pending = undefined;
+      });
+    }
+    return this.pending;
+  }
+}

package/src/services/SessionManager.ts

@@ -5,10 +5,12 @@ import * as fs from "fs";
 import * as fsPromises from "fs/promises";
 import * as path from "path";
 import { TaskInfo, ChatSession } from "../chat/types";
+import { TraceAll } from "../util/Trace";
 
 /**
  * SessionManager handles saving, loading, and managing agent sessions
  */
+@TraceAll()
 export class SessionManager {
   private sessionsDir: string;
 
@@ -69,6 +71,7 @@ export class SessionManager {
         provider: taskInfo.provider,
         reasoningEffort: taskInfo.reasoningEffort,
         summarizeReasoning: taskInfo.summarizeReasoning,
+        enabledTools: taskInfo.enabledTools,
       };
 
       fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));
@@ -115,6 +118,8 @@ export class SessionManager {
             session.reasoningEffort = taskInfo.reasoningEffort;
           if (taskInfo.summarizeReasoning !== undefined)
             session.summarizeReasoning = taskInfo.summarizeReasoning;
+          if (taskInfo.enabledTools !== undefined)
+            session.enabledTools = taskInfo.enabledTools;
         }
 
         fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));

package/src/services/SkillsService.ts

@@ -4,6 +4,7 @@ import * as os from "os";
 import { createHash } from "crypto";
 import * as https from "https";
 import { KnowhowSimpleClient } from "./KnowhowClient";
+import { TraceAll } from "../util/Trace";
 
 // Default local install dir (relative to cwd)
 const LOCAL_SKILLS_DIR = ".knowhow/skills";
@@ -233,6 +234,7 @@ export function parseSkillRef(
   return { owner, repo, skill, sourceUrl };
 }
 
+@TraceAll()
 export class SkillsService {
   private cwd: string;
   private isGlobal: boolean;

package/src/services/SyncedAgentWatcher.ts

@@ -5,6 +5,7 @@
 
 import { Message } from "../clients/types";
 import { EventService } from "./EventService";
+import { TraceAll } from "../util/Trace";
 
 export interface SyncedAgentWatcher {
   /** Start watching for changes, emitting agent events */
@@ -73,6 +74,7 @@ export interface AttachableAgent {
  * - agentEvents and eventTypes are delegated to the watcher
  * - "done" is emitted by the watcher when the remote agent completes
  */
+@TraceAll()
 export class WatcherBackedAgent implements AttachableAgent {
   public name: string;
   public agentEvents: EventService;

package/src/services/SyncerService.ts

@@ -3,6 +3,7 @@
  * Hides complexity of choosing and managing sync backends.
  */
 import { BaseAgent } from "../agents/base/base";
+import { TraceAll } from "../util/Trace";
 import { AgentSyncFs } from "./AgentSyncFs";
 import { AgentSyncKnowhowWeb } from "./AgentSyncKnowhowWeb";
 
@@ -11,12 +12,13 @@ export interface SyncerOptions {
   prompt: string;
   /** If provided → use web sync (unless syncFs is set) */
   messageId?: string;
+  /** Existing remote Knowhow task UUID. Never inferred from the local taskId. */
+  remoteTaskId?: string;
   /** Force fs sync even if messageId is provided */
   syncFs?: boolean;
   /**
-   * Push the agent's work to a remote Knowhow task. When set (and there is no
-   * messageId), the `taskId` is treated as the remote task ID to attach to and
-   * push updates to, rather than creating a new remote task.
+   * Push the agent's work to the existing `remoteTaskId`. The local taskId is
+   * always a filesystem identity and is never used as a remote identifier.
    */
   syncRemote?: boolean;
   /** Agent name to persist in metadata.json */
@@ -44,8 +46,9 @@ export interface AgentSyncer {
  * Decision logic:
  *   - Always sets up AgentSyncFs (primary local syncer)
  *   - If messageId is present AND syncFs is not forced → creates a new remote task via AgentSyncKnowhowWeb
- *   - If syncRemote is set (and no messageId) → attaches to the remote task identified by taskId
+ *   - If syncRemote and a valid remoteTaskId are set → attaches to that UUID
  */
+@TraceAll()
 export class SyncerService implements AgentSyncer {
   private fsSync: AgentSyncFs;
   private webSync: AgentSyncKnowhowWeb;
@@ -75,14 +78,16 @@ export class SyncerService implements AgentSyncer {
 
     // Determine whether to ATTACH to an already-existing remote task and push
     // local work to it (no creation needed). This is the "--sync-remote" path:
-    // the caller wants to push work to the remote task identified by taskId.
+    // the caller wants to push work to an explicitly identified remote task.
     // We only auto-attach when there is NO messageId (messageId always creates
     // a fresh remote task above).
     //
     // This is orthogonal to fs sync: we can push to the remote task AND keep
     // the local .knowhow/processes/agents/<id>/ files in sync at the same time.
     const shouldAttachExisting =
-      !!options.syncRemote && !options.messageId && !!options.taskId;
+      !!options.syncRemote &&
+      !options.messageId &&
+      isUuid(options.remoteTaskId);
 
     // Always create fs sync task first
     console.log(
@@ -104,6 +109,7 @@ export class SyncerService implements AgentSyncer {
 
       if (knowhowTaskId) {
         this.useWebSync = true;
+        await this.fsSync.setRemoteIdentity(knowhowTaskId, options.messageId);
         this.createdTaskId = knowhowTaskId;
         console.log(`🌐 Web sync task created: ${knowhowTaskId}`);
       }
@@ -112,9 +118,10 @@ export class SyncerService implements AgentSyncer {
     // Attach live web sync to an existing remote task (push updates to it).
     if (!shouldUseWebSync && shouldAttachExisting) {
       this.useWebSync = true;
-      this.createdTaskId = options.taskId;
+      await this.fsSync.setRemoteIdentity(options.remoteTaskId!);
+      this.createdTaskId = options.remoteTaskId;
       console.log(
-        `🌐 Attaching web sync to existing remote task: ${options.taskId}`
+        `🌐 Attaching web sync to existing remote task: ${options.remoteTaskId}`
       );
     }
 
@@ -174,3 +181,11 @@ export class SyncerService implements AgentSyncer {
     return this.useWebSync ? this.createdTaskId : undefined;
   }
 }
+
+/** Remote task IDs are UUIDs; local filesystem IDs are timestamped slugs. */
+function isUuid(value: string | undefined): value is string {
+  return !!value &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      value
+    );
+}

package/src/services/TaskRegistry.ts

@@ -2,10 +2,12 @@
  * Task Registry Service - Manages active agent tasks
  */
 import { TaskInfo } from "../chat/types";
+import { TraceAll } from "../util/Trace";
 
 /**
  * TaskRegistry manages the in-memory registry of active agent tasks
  */
+@TraceAll()
 export class TaskRegistry {
   private tasks = new Map<string, TaskInfo>();