@tyvm/knowhow 0.0.146 → 0.0.147

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>();
 

package/src/services/Tools.ts

@@ -1,4 +1,5 @@
 import { ChatCompletionTool } from "openai/resources/chat";
+import { TraceAll } from "../util/Trace";
 import { replaceEscapedNewLines, restoreEscapedNewLines } from "../utils";
 import { includedTools } from "../agents/tools/list";
 import { AgentService } from "./AgentService";
@@ -61,6 +62,7 @@ export interface ToolContext {
  * larger context bloat from having every tool defined in system prompt
  *
  */
+@TraceAll()
 export class ToolsService {
   private context: ToolContext = {};
 

package/src/services/index.ts

@@ -51,6 +51,7 @@ let Singletons = {} as {
   Tools: ToolsService;
   Events: EventService;
   Agents: AgentService;
+  Tracing: typeof TracingService;
   Embeddings: EmbeddingsService;
   Flags: FlagsService;
   Mcp: McpService;
@@ -83,6 +84,7 @@ export const services = (): typeof Singletons => {
     Singletons = {
       Agents,
       AwsS3: new S3Service(),
+      Tracing: TracingService,
       Clients,
       Docker: new DockerService(),
       Events,

package/src/services/modules/index.ts

@@ -284,9 +284,12 @@ export class ModulesService {
 
     // Load global-config modules resolving against the global install's
     // node_modules (~/.knowhow/node_modules) first.
+    // Pass a merged config so that keys defined in the global config (e.g.
+    // `tracing`) are visible to globally-declared modules during init().
+    // Local config keys take precedence so that local overrides still work.
     if (globalModules.length > 0) {
       await this.loadModulesFrom(
-        { ...config, modules: globalModules },
+        { ...globalConfig, ...config, modules: globalModules },
         context,
         globalResolvePaths()
       );

package/src/types.ts

@@ -75,6 +75,8 @@ export type Config = {
   promptsDir: string;
   lintCommands?: { [fileExtension: string]: string };
   orgId?: string;
+  /** Private Ed25519 identity selected with `knowhow login --identity`. */
+  cliIdentityPath?: string;
   syncRemote?: boolean;
   micCommand?: string;
   defaultMic?: string;

package/src/util/Trace.ts

@@ -141,7 +141,7 @@ export interface TraceAllOptions {
 export function TraceAll(options: TraceAllOptions = {}) {
   const skip = new Set(options.skip ?? []);
 
-  return function <T extends { new (...args: unknown[]): object }>(
+  return function <T extends abstract new (...args: unknown[]) => object>(
     constructor: T
   ): T {
     const className = constructor.name;

package/src/utils/http.ts

@@ -21,6 +21,15 @@ export class HttpError extends Error {
   }
 }
 
+/**
+ * Optional, non-enumerable hook carried by an authenticated headers object.
+ * The hook may replace an expired credential before one safe 401 retry.
+ */
+export const HTTP_UNAUTHORIZED_HANDLER = Symbol("httpUnauthorizedHandler");
+export type RefreshableHeaders = Record<string, string> & {
+  [HTTP_UNAUTHORIZED_HANDLER]?: () => Promise<void>;
+};
+
 async function parseBody<T>(response: Response, responseType?: string): Promise<T> {
   if (responseType === "arraybuffer") {
     return (await response.arrayBuffer()) as unknown as T;
@@ -41,13 +50,14 @@ async function request<T = any>(
   url: string,
   options: {
     method?: string;
-    headers?: Record<string, string>;
+    headers?: RefreshableHeaders;
     body?: any;
     responseType?: "json" | "arraybuffer" | "stream" | "text";
     params?: Record<string, any>;
     /** Timeout in milliseconds. Default: 30000 (30s). Use 0 to disable. */
     timeout?: number;
-  } = {}
+  } = {},
+  mayRefresh = true
 ): Promise<HttpResponse<T>> {
   const { method = "GET", headers = {}, body, responseType, params, timeout = 30000 } = options;
 
@@ -102,6 +112,12 @@ async function request<T = any>(
   }
 
   if (!response.ok) {
+    const refresh = headers[HTTP_UNAUTHORIZED_HANDLER];
+    if (response.status === 401 && mayRefresh && refresh) {
+      await refresh();
+      return request<T>(url, options, false);
+    }
+
     const text = await response.text().catch(() => "");
     let parsedBody: any;
     try {

package/tests/unit/agents/historyRollback.test.ts

@@ -0,0 +1,53 @@
+import { rollbackAgentInteractions } from "../../../src/agents/historyRollback";
+import { Message } from "../../../src/clients/types";
+
+const message = (role: Message["role"], content: string): Message => ({ role, content });
+
+describe("rollbackAgentInteractions", () => {
+  const threads: Message[][] = [[
+    message("user", "request"),
+    message("assistant", "first"),
+    message("tool", "first result"),
+    message("assistant", "second"),
+    message("tool", "second result"),
+  ]];
+
+  it("clones history without changing it when rollback is zero", () => {
+    const result = rollbackAgentInteractions(threads, 0);
+    expect(result).toEqual(threads);
+    expect(result).not.toBe(threads);
+    expect(result[0]).not.toBe(threads[0]);
+    expect(result[0][0]).not.toBe(threads[0][0]);
+  });
+
+  it("removes the newest assistant and its following tool results", () => {
+    expect(rollbackAgentInteractions(threads, 1)).toEqual([threads[0].slice(0, 3)]);
+  });
+
+  it("can remove multiple interactions", () => {
+    expect(rollbackAgentInteractions(threads, 2)).toEqual([[threads[0][0]]]);
+  });
+
+  it("removes a trailing assistant without tools", () => {
+    const input = [[message("user", "request"), message("assistant", "tail")]];
+    expect(rollbackAgentInteractions(input, 1)).toEqual([[input[0][0]]]);
+  });
+
+  it.each([-1, 1.5])("rejects invalid rollback %p", (rollback) => {
+    expect(() => rollbackAgentInteractions(threads, rollback)).toThrow(
+      "rollback must be a non-negative integer"
+    );
+  });
+
+  it("rejects rollback beyond available interactions", () => {
+    expect(() => rollbackAgentInteractions(threads, 3)).toThrow(
+      "only has 2 assistant interaction(s)"
+    );
+  });
+
+  it("does not mutate input history", () => {
+    const before = JSON.stringify(threads);
+    rollbackAgentInteractions(threads, 1);
+    expect(JSON.stringify(threads)).toBe(before);
+  });
+});

package/tests/unit/auth/keyAuth.test.ts

@@ -0,0 +1,102 @@
+const post = jest.fn();
+const publicKeyBase64 = Buffer.alloc(32, 7).toString("base64");
+const keyPairExists = jest.fn(() => true);
+const loadKeyPair = jest.fn(() => ({ publicKeyBase64 }));
+const signMessage = jest.fn(() => "server-message-signature");
+
+jest.mock("../../../src/utils/http", () => ({
+  __esModule: true,
+  default: {
+    post,
+    isHttpError: (error: unknown) =>
+      typeof error === "object" && error !== null && "status" in error,
+  },
+}));
+
+jest.mock("../../../src/auth/keyManager", () => ({
+  keyPairExists,
+  loadKeyPair,
+  signMessage,
+}));
+
+jest.mock("../../../src/auth/browserLogin", () => ({
+  getCliUserAgent: () => "test-agent",
+}));
+
+import {
+  authenticateWithKey,
+  exchangePublicKeyJwt,
+  hasKeyPair,
+  registerPublicKey,
+} from "../../../src/auth/keyAuth";
+
+describe("keyAuth", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    keyPairExists.mockReturnValue(true);
+  });
+
+  it("signs the exact server challenge for the selected key, org, and environment", async () => {
+    post
+      .mockResolvedValueOnce({
+        data: {
+          challengeId: "challenge_1",
+          message: "exact message from server",
+          expiresAt: "2099-01-01T00:00:00.000Z",
+        },
+        status: 201,
+      })
+      .mockResolvedValueOnce({ data: { jwt: "renewed-jwt" }, status: 200 });
+
+    expect(hasKeyPair("/keys/work")).toBe(true);
+    await expect(
+      exchangePublicKeyJwt("org-1", "https://work.example", "/keys/work")
+    ).resolves.toBe("renewed-jwt");
+
+    expect(loadKeyPair).toHaveBeenCalledWith("/keys/work");
+    expect(signMessage).toHaveBeenCalledWith("exact message from server", "/keys/work");
+    expect(post.mock.calls).toEqual([
+      [
+        "https://work.example/api/public-keys/challenge",
+        { publicKey: publicKeyBase64, orgId: "org-1" },
+        { headers: { "User-Agent": "test-agent" } },
+      ],
+      [
+        "https://work.example/api/public-keys/authenticate",
+        { challengeId: "challenge_1", signature: "server-message-signature" },
+        { headers: { "User-Agent": "test-agent" } },
+      ],
+    ]);
+  });
+
+  it("falls back when the key is unavailable without signing a challenge", async () => {
+    post.mockRejectedValueOnce({ status: 401 });
+
+    await expect(
+      authenticateWithKey("org-1", "https://work.example", "/keys/work")
+    ).resolves.toBe(false);
+
+    expect(post).toHaveBeenCalledTimes(1);
+    expect(signMessage).not.toHaveBeenCalled();
+  });
+
+  it("registers only server-owned Ed25519 key fields in the selected environment", async () => {
+    post.mockResolvedValueOnce({ data: {}, status: 201 });
+
+    await registerPublicKey("browser-jwt", publicKeyBase64, "https://dev.example");
+
+    expect(post).toHaveBeenCalledWith(
+      "https://dev.example/api/public-keys/register",
+      {
+        publicKey: publicKeyBase64,
+        label: expect.any(String),
+      },
+      {
+        headers: {
+          Authorization: "Bearer browser-jwt",
+          "User-Agent": "test-agent",
+        },
+      }
+    );
+  });
+});

package/tests/unit/auth/keyManager.test.ts

@@ -0,0 +1,67 @@
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import {
+  generateKeyPair,
+  loadKeyPair,
+  signMessage,
+} from "../../../src/auth/keyManager";
+
+describe("keyManager", () => {
+  let directory: string;
+  let identity: string;
+
+  beforeEach(() => {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-key-manager-"));
+    identity = path.join(directory, "identity");
+  });
+
+  afterEach(() => {
+    fs.rmSync(directory, { recursive: true, force: true });
+  });
+
+  it("creates an Ed25519 identity with an OpenSSH-compatible public key", () => {
+    const generated = generateKeyPair(identity);
+    const publicKeyLine = fs.readFileSync(`${identity}.pub`, "utf8").trim();
+
+    expect(publicKeyLine).toMatch(/^ssh-ed25519 [A-Za-z0-9+/]+=* knowhow-cli$/);
+    expect(fs.statSync(identity).mode % 0o1000).toBe(0o600);
+    expect(loadKeyPair(identity)).toEqual(generated);
+
+    const challengeMessage = "exact server-provided challenge";
+    const signature = signMessage(challengeMessage, identity);
+    const publicKey = crypto.createPublicKey(fs.readFileSync(identity));
+    expect(
+      crypto.verify(
+        null,
+        Buffer.from(challengeMessage),
+        publicKey,
+        Buffer.from(signature, "base64")
+      )
+    ).toBe(true);
+  });
+
+  it("loads legacy raw-base64 public keys but rejects non-Ed25519 identities", () => {
+    const generated = generateKeyPair(identity);
+    fs.writeFileSync(`${identity}.pub`, generated.publicKeyBase64);
+    expect(loadKeyPair(identity).publicKeyBase64).toBe(generated.publicKeyBase64);
+
+    const rsaIdentity = path.join(directory, "rsa");
+    const rsa = crypto.generateKeyPairSync("rsa", {
+      modulusLength: 2048,
+      privateKeyEncoding: { type: "pkcs8", format: "pem" },
+      publicKeyEncoding: { type: "spki", format: "pem" },
+    });
+    fs.writeFileSync(rsaIdentity, rsa.privateKey);
+    fs.writeFileSync(`${rsaIdentity}.pub`, generated.publicKeyBase64);
+
+    expect(() => loadKeyPair(rsaIdentity)).toThrow("must be an Ed25519 private key");
+  });
+
+  it("does not overwrite a partial identity", () => {
+    fs.writeFileSync(identity, "existing key");
+    expect(() => generateKeyPair(identity)).toThrow("a key file already exists");
+    expect(fs.readFileSync(identity, "utf8")).toBe("existing key");
+  });
+});

package/tests/unit/chat/historyCommandArgs.test.ts

@@ -0,0 +1,37 @@
+import { parseHistoryCommandArgs } from "../../../src/chat/modules/SessionsModule";
+
+describe("parseHistoryCommandArgs", () => {
+  it("parses an id and rollback in either order", () => {
+    expect(parseHistoryCommandArgs(["task-1", "--rollback", "2"])).toEqual({
+      id: "task-1", rollback: 2, showAll: false,
+    });
+    expect(parseHistoryCommandArgs(["--rollback", "1", "task-1"])).toEqual({
+      id: "task-1", rollback: 1, showAll: false,
+    });
+  });
+
+  it("supports interactive --all", () => {
+    expect(parseHistoryCommandArgs(["--all"])).toEqual({
+      id: undefined, rollback: 0, showAll: true,
+    });
+  });
+
+  it.each([
+    [["--rollback"]],
+    [["--rollback", "-1"]],
+    [["--rollback", "1.5"]],
+  ])(
+    "rejects invalid rollback arguments: %p",
+    (args) => {
+      expect(() => parseHistoryCommandArgs(args)).toThrow(
+        "--rollback must be a non-negative integer"
+      );
+    }
+  );
+
+  it("rejects unexpected arguments", () => {
+    expect(() => parseHistoryCommandArgs(["one", "two"])).toThrow(
+      "Unexpected argument: two"
+    );
+  });
+});

package/tests/unit/commands/agents.test.ts

@@ -0,0 +1,68 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { Command } from "commander";
+
+const startChat = jest.fn().mockResolvedValue(undefined);
+const setupServices = jest.fn().mockResolvedValue(undefined);
+
+jest.mock("../../../src/chat", () => ({ startChat }));
+jest.mock("../../../src/commands/services", () => ({ setupServices }));
+
+import { addAgentsCommand } from "../../../src/commands/agents";
+
+describe("agents resume terminal UX", () => {
+  let previousCwd: string;
+  let tempDir: string;
+  let isTTYDescriptor: PropertyDescriptor | undefined;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    previousCwd = process.cwd();
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-agents-command-"));
+    process.chdir(tempDir);
+    const taskId = "1700000000-resumable-task";
+    fs.mkdirSync(path.join(".knowhow", "processes", "agents", taskId), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      path.join(".knowhow", "processes", "agents", taskId, "metadata.json"),
+      JSON.stringify({ taskId, status: "completed", threads: [[]] })
+    );
+    isTTYDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+    Object.defineProperty(process.stdin, "isTTY", {
+      configurable: true,
+      value: true,
+    });
+  });
+
+  afterEach(() => {
+    process.chdir(previousCwd);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    if (isTTYDescriptor) {
+      Object.defineProperty(process.stdin, "isTTY", isTTYDescriptor);
+    } else {
+      delete (process.stdin as NodeJS.ReadStream & { isTTY?: boolean }).isTTY;
+    }
+  });
+
+  test("opens chat with the interactive resume command by default", async () => {
+    const program = new Command();
+    addAgentsCommand(program, jest.fn());
+
+    await program.parseAsync([
+      "node",
+      "knowhow",
+      "agents",
+      "resume",
+      "1700000000-resumable-task",
+      "--rollback",
+      "2",
+    ]);
+
+    expect(setupServices).toHaveBeenCalledTimes(1);
+    expect(startChat).toHaveBeenCalledWith(
+      "/resume 1700000000-resumable-task --rollback 2"
+    );
+  });
+});

package/tests/unit/login.test.ts

@@ -0,0 +1,119 @@
+const httpGet = jest.fn();
+const browserLogin = jest.fn();
+const hasKeyPair = jest.fn();
+const authenticateWithKey = jest.fn();
+const registerPublicKey = jest.fn();
+const getOrCreatePublicKey = jest.fn();
+const getConfig = jest.fn();
+const updateConfig = jest.fn();
+
+jest.mock("../../src/utils/http", () => ({
+  __esModule: true,
+  default: { get: httpGet, isHttpError: () => false },
+}));
+
+jest.mock("../../src/services/KnowhowClient", () => ({
+  KNOWHOW_API_URL: "https://api.example",
+}));
+
+jest.mock("../../src/auth/browserLogin", () => ({
+  BrowserLoginService: jest.fn().mockImplementation(() => ({ login: browserLogin })),
+}));
+
+jest.mock("../../src/auth/keyAuth", () => ({
+  hasKeyPair,
+  authenticateWithKey,
+  registerPublicKey,
+}));
+
+jest.mock("../../src/auth/keyManager", () => ({ getOrCreatePublicKey }));
+jest.mock("../../src/config", () => ({ getConfig, updateConfig }));
+jest.mock("../../src/utils", () => ({ ask: jest.fn() }));
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { login } from "../../src/login";
+
+describe("login public-key bootstrap", () => {
+  const originalCwd = process.cwd();
+  let workingDirectory: string;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(console, "log").mockImplementation(() => undefined);
+    jest.spyOn(console, "warn").mockImplementation(() => undefined);
+    workingDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-login-"));
+    fs.mkdirSync(path.join(workingDirectory, ".knowhow"));
+    fs.writeFileSync(path.join(workingDirectory, ".knowhow", ".jwt"), "raw-jwt");
+    process.chdir(workingDirectory);
+    hasKeyPair.mockReturnValue(false);
+    browserLogin.mockResolvedValue(undefined);
+    getConfig.mockResolvedValue({ modelProviders: [] });
+    getOrCreatePublicKey.mockReturnValue({
+      publicKeyBase64: "raw-key",
+      fingerprint: "SHA256:key",
+    });
+    httpGet.mockResolvedValue({
+      data: {
+        orgId: "org-1",
+        user: {
+          email: "user@example.com",
+          orgs: [{ organizationId: "org-1", organization: { id: "org-1", name: "Org" } }],
+        },
+      },
+    });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(workingDirectory, { recursive: true, force: true });
+    jest.restoreAllMocks();
+  });
+
+  it("bootstraps the selected identity after PKCE without invalidating browser login on registration failure", async () => {
+    registerPublicKey.mockRejectedValueOnce(new Error("endpoint unavailable"));
+
+    await expect(login(false, "/keys/custom")).resolves.toBeUndefined();
+
+    expect(browserLogin).toHaveBeenCalledTimes(1);
+    expect(getOrCreatePublicKey).toHaveBeenCalledWith("/keys/custom");
+    expect(registerPublicKey).toHaveBeenCalledWith(
+      "raw-jwt",
+      "raw-key",
+      "https://api.example"
+    );
+    expect(updateConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ orgId: "org-1", modelProviders: [{ provider: "knowhow" }] })
+    );
+  });
+
+  it("safely falls back to browser PKCE when the selected key cannot authenticate", async () => {
+    hasKeyPair.mockReturnValue(true);
+    getConfig.mockResolvedValue({ orgId: "org-1", modelProviders: [] });
+    authenticateWithKey.mockRejectedValueOnce(new Error("old backend"));
+    registerPublicKey.mockResolvedValueOnce(undefined);
+
+    await expect(login(false, "/keys/dev")).resolves.toBeUndefined();
+
+    expect(authenticateWithKey).toHaveBeenCalledWith(
+      "org-1",
+      "https://api.example",
+      "/keys/dev"
+    );
+    expect(browserLogin).toHaveBeenCalledTimes(1);
+    expect(getOrCreatePublicKey).toHaveBeenCalledWith("/keys/dev");
+  });
+
+  it("does not attempt key authentication without a configured organization", async () => {
+    hasKeyPair.mockReturnValue(true);
+    getConfig.mockResolvedValue({ modelProviders: [] });
+    registerPublicKey.mockResolvedValueOnce(undefined);
+
+    await expect(login(false, "/keys/dev")).resolves.toBeUndefined();
+
+    expect(hasKeyPair).not.toHaveBeenCalled();
+    expect(authenticateWithKey).not.toHaveBeenCalled();
+    expect(browserLogin).toHaveBeenCalledTimes(1);
+  });
+});