@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/codeAgent/agent/WorkspaceTrust.ts

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { McpServerConfig } from "../tools/McpServerConfig";
+import { akanCodePaths } from "./akanCodePaths";
+
+export type WorkspaceTrustKind = "mcp" | "extensions";
+
+export interface WorkspaceTrustItem {
+  kind: WorkspaceTrustKind;
+  lines: string[];
+  hash: string;
+}
+
+type TrustRecord = Partial<Record<WorkspaceTrustKind, string>>;
+
+interface ExtensionWalk {
+  root: string;
+  files: { name: string; path: string }[];
+  bytes: number;
+  seen: Set<string>;
+  unchecked?: string;
+}
+
+const maxExtensionFiles = 10_000;
+const maxExtensionBytes = 64 * 1024 * 1024;
+
+// A repo's mcp.json starts processes and its extensions/ load as code, so each waits for a yes to its exact content.
+export class WorkspaceTrust {
+  static readonly #granted = new Map<string, string>();
+
+  static items(workspaceRoot: string, kinds: WorkspaceTrustKind[] = ["mcp", "extensions"]) {
+    return kinds
+      .map((kind) => WorkspaceTrust.#itemOf(workspaceRoot, kind))
+      .filter((item): item is WorkspaceTrustItem => !!item);
+  }
+
+  static pending(workspaceRoot: string, kinds?: WorkspaceTrustKind[]) {
+    return WorkspaceTrust.items(workspaceRoot, kinds).filter((item) => !WorkspaceTrust.#approved(workspaceRoot, item));
+  }
+
+  static isTrusted(workspaceRoot: string, kind: WorkspaceTrustKind) {
+    const item = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    return !item || WorkspaceTrust.#approved(workspaceRoot, item);
+  }
+
+  static approve(workspaceRoot: string, items: WorkspaceTrustItem[], remember: boolean) {
+    const key = WorkspaceTrust.#keyOf(workspaceRoot);
+    for (const item of items) WorkspaceTrust.#granted.set(`${key}\n${item.kind}`, item.hash);
+    const checked = items.filter((item) => item.hash);
+    if (!remember || !checked.length) return;
+    const all = WorkspaceTrust.#read();
+    const record: TrustRecord = { ...all[key] };
+    for (const item of checked) record[item.kind] = item.hash;
+    WorkspaceTrust.#write({ ...all, [key]: record });
+  }
+
+  static carry<T>(workspaceRoot: string, kind: WorkspaceTrustKind, edit: () => T): T {
+    const before = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    const trusted = !before || WorkspaceTrust.#approved(workspaceRoot, before);
+    const remembered = !before || WorkspaceTrust.#read()[WorkspaceTrust.#keyOf(workspaceRoot)]?.[kind] === before.hash;
+    const result = edit();
+    const after = WorkspaceTrust.#itemOf(workspaceRoot, kind);
+    if (trusted && after) WorkspaceTrust.approve(workspaceRoot, [after], remembered);
+    return result;
+  }
+
+  static #approved(workspaceRoot: string, item: WorkspaceTrustItem) {
+    const key = WorkspaceTrust.#keyOf(workspaceRoot);
+    return (
+      WorkspaceTrust.#granted.get(`${key}\n${item.kind}`) === item.hash ||
+      (!!item.hash && WorkspaceTrust.#read()[key]?.[item.kind] === item.hash)
+    );
+  }
+
+  static #itemOf(workspaceRoot: string, kind: WorkspaceTrustKind): WorkspaceTrustItem | undefined {
+    return kind === "mcp" ? WorkspaceTrust.#mcp(workspaceRoot) : WorkspaceTrust.#extensions(workspaceRoot);
+  }
+
+  static #mcp(workspaceRoot: string): WorkspaceTrustItem | undefined {
+    const servers = McpServerConfig.read(workspaceRoot, ["workspace"]).sort((a, b) => a.name.localeCompare(b.name));
+    if (!servers.length) return undefined;
+    return {
+      kind: "mcp",
+      lines: servers.map((ref) => `${ref.name}: ${McpServerConfig.targetOf(ref)}`),
+      hash: WorkspaceTrust.#digest(WorkspaceTrust.#canonical(servers)),
+    };
+  }
+
+  //? An item without a hash could not be checked: the trust file never keeps it, so it is asked about at every start.
+  static #extensions(workspaceRoot: string): WorkspaceTrustItem | undefined {
+    const dir = akanCodePaths.extensionsDir(workspaceRoot);
+    let root: string;
+    try {
+      root = realpathSync(dir);
+    } catch {
+      return undefined;
+    }
+    const walk: ExtensionWalk = { root, files: [], bytes: 0, seen: new Set() };
+    WorkspaceTrust.#walk(walk, dir, "");
+    const lines = walk.files.map((file) => file.name);
+    if (walk.unchecked) return { kind: "extensions", lines: [walk.unchecked, ...lines], hash: "" };
+    if (!walk.files.length) return undefined;
+    const hash = createHash("sha256");
+    for (const file of walk.files) hash.update(`${file.name}\0${WorkspaceTrust.#digest(readFileSync(file.path))}\n`);
+    return { kind: "extensions", lines, hash: hash.digest("hex") };
+  }
+
+  // Links are followed while they stay in the folder, since the engine follows them too.
+  static #walk(walk: ExtensionWalk, dir: string, prefix: string) {
+    let entries: string[];
+    try {
+      const real = realpathSync(dir);
+      if (walk.seen.has(real)) return;
+      walk.seen.add(real);
+      entries = readdirSync(dir)
+        .filter((entry) => entry !== ".git")
+        .sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (walk.unchecked) return;
+      const full = path.join(dir, entry);
+      const name = prefix ? `${prefix}/${entry}` : entry;
+      try {
+        if (lstatSync(full).isSymbolicLink() && !WorkspaceTrust.#inside(walk.root, realpathSync(full))) {
+          walk.unchecked = `${name} links out of the folder: it cannot be checked, so it is asked about at every start`;
+          return;
+        }
+        const stat = statSync(full);
+        if (stat.isDirectory()) WorkspaceTrust.#walk(walk, full, name);
+        else if (stat.isFile()) {
+          walk.files.push({ name, path: full });
+          walk.bytes += stat.size;
+          if (walk.files.length > maxExtensionFiles || walk.bytes > maxExtensionBytes)
+            walk.unchecked = `more than ${maxExtensionFiles} files or ${maxExtensionBytes >> 20} MiB: too many to check, so asked about at every start`;
+        }
+      } catch {}
+    }
+  }
+
+  static #inside(root: string, real: string) {
+    const relative = path.relative(root, real);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+  }
+
+  static #keyOf(workspaceRoot: string) {
+    try {
+      return realpathSync(workspaceRoot);
+    } catch {
+      return path.resolve(workspaceRoot);
+    }
+  }
+
+  static #digest(content: string | Buffer) {
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  static #canonical(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map((entry) => WorkspaceTrust.#canonical(entry)).join(",")}]`;
+    if (value && typeof value === "object")
+      return `{${Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${WorkspaceTrust.#canonical(entry)}`)
+        .join(",")}}`;
+    return JSON.stringify(value);
+  }
+
+  static #read(): Record<string, TrustRecord> {
+    const file = akanCodePaths.trustFile();
+    if (!existsSync(file)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { workspaces?: Record<string, TrustRecord> };
+      return parsed.workspaces ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  static #write(workspaces: Record<string, TrustRecord>) {
+    akanCodePaths.ensureGlobalDir();
+    const file = akanCodePaths.trustFile();
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ workspaces }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    chmodSync(file, 0o600);
+  }
+}

package/codeAgent/agent/akanCodePaths.ts

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { FileSys } from "../../fileSys";
+import { AkanCodeEnv } from "./AkanCodeEnv";
 
 // Two candidates: the CLI bundle flattens entry chunks into the package root, where `skills/` is a sibling.
 const builtinSkillsDir = () => {
@@ -9,7 +11,9 @@ const builtinSkillsDir = () => {
 };
 
 // One override for the whole set, so a `models.json` and the `auth.json` it names never drift apart.
-const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
+const globalDir = () => AkanCodeEnv.get("AKAN_CODE_HOME") ?? path.join(homedir(), ".akan", "code");
+
+const ensureGlobalDir = () => FileSys.ensurePrivateDir(globalDir());
 
 // Credentials live under the home directory, never the repo: a repo is what gets committed, zipped and shared.
 export const akanCodePaths = {
@@ -24,8 +28,11 @@ export const akanCodePaths = {
   globalMcpFile: () => path.join(globalDir(), "mcp.json"),
   globalSkillsDir: () => path.join(globalDir(), "skills"),
   globalDir,
+  ensureGlobalDir,
   authFile: () => path.join(globalDir(), "auth.json"),
   /** MCP bearer tokens, beside the provider keys and for the same reason: never in a directory that is shared. */
   mcpAuthFile: () => path.join(globalDir(), "mcpAuth.json"),
   modelsFile: () => path.join(globalDir(), "models.json"),
+  trustFile: () => path.join(globalDir(), "trust.json"),
+  rpcTokenFile: (port: number) => path.join(globalDir(), "rpc", `${port}.token`),
 } as const;

package/codeAgent/agent/akanSystemPrompt.ts

@@ -13,7 +13,7 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
   ];
   if (profile.tools.builtin.includes("write"))
     lines.push(
-      "- After editing, call `akan_verify`. It runs sync, lint, typecheck and the SSR check over what the working tree changed. A turn that edits and does not verify is not finished.",
+      "- After editing, call `akan_verify` once. It runs sync, lint, typecheck, a fast build and the SSR check over what the working tree changed; never run `akan lint`, `akan typecheck` or `akan build` separately. A turn that edits and does not verify is not finished.",
     );
   else
     lines.push(
@@ -31,6 +31,10 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     lines.push(
       `- Some tool calls need the user's approval (policy: ${profile.approval}). A refusal is an answer; do not retry it a different way.`,
     );
+  if (profile.network.askOutside)
+    lines.push(
+      "- `web_fetch` to a host outside a short list of documentation sites, and a shell command that reaches the network (`curl`, `wget`, `ssh`, …), wait for the user's approval. A refusal is an answer; do not retry it a different way.",
+    );
   lines.push(
     "- Secrets are refused at the tool boundary. If you need a value from `.env`, ask the user for it rather than looking for another way to read the file.",
     "",

package/codeAgent/agent/codeAgent.test.ts

@@ -6,7 +6,7 @@ import { type CodeAgentEvent, type CodeAgentProfile, codeAgentPresets } from "ak
 import { WorkspaceExecutor } from "../../executors";
 import { isolateEnv, tempDirs } from "../../testHelpers";
 import { AkanCodePlugins } from "../tools/AkanCodePlugins";
-import { akanCodeDefaultModel } from "./akanCodeModel";
+import { akanCodeDefaultModel, type CodeAgentModelRef } from "./akanCodeModel";
 import { akanCodePaths } from "./akanCodePaths";
 import { CodeAgent, type CodeAgentOptions } from "./CodeAgent";
 import { CodeAgentSuspended } from "./CodeAgentSuspended";
@@ -37,11 +37,14 @@ const usageChunk = (promptTokens: number) =>
 let llm: ReturnType<typeof Bun.serve>;
 let llmCalls = 0;
 let reportedTokens = 0;
+const requestedModels: string[] = [];
 beforeAll(() => {
   llm = Bun.serve({
     port: 0,
-    fetch: () => {
+    fetch: async (request) => {
       llmCalls += 1;
+      const body = (await request.json().catch(() => ({}))) as { model?: string };
+      requestedModels.push(body.model ?? "");
       const usage = reportedTokens ? usageChunk(reportedTokens) : "";
       return new Response(
         `${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}${usage}data: [DONE]\n\n`,
@@ -160,6 +163,42 @@ describe("CodeAgent", () => {
       spy.mockRestore();
     }
   });
+
+  test("a task child sends its requests on the parent's model, and on the one the parent switches to", async () => {
+    const root = await makeTempRoot();
+    const build = AkanCodePlugins.build;
+    let parentModel: (() => CodeAgentModelRef | undefined) | undefined;
+    const spy = spyOn(AkanCodePlugins, "build").mockImplementation(async (options) => {
+      parentModel = options.model;
+      return await build.call(AkanCodePlugins, options);
+    });
+    const agent = await createAgent(root, { model: { provider: "deepseek", id: "deepseek-v4-pro" } });
+    spy.mockRestore();
+    const profile = quietProfile(root);
+    const pool = SubagentPool.extensionFor({
+      workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+      cwd: root,
+      parent: { ...profile, tools: { ...profile.tools, subagent: { maxDepth: 2, maxConcurrent: 3, budget: 100_000 } } },
+      ...(parentModel ? { model: parentModel } : {}),
+      depth: 0,
+    });
+    let execute: ((id: string, params: never) => Promise<unknown>) | undefined;
+    if (pool && "factory" in pool)
+      pool.factory({
+        registerTool: (tool: { execute: typeof execute }) => {
+          execute = tool.execute;
+        },
+      } as never);
+    try {
+      requestedModels.length = 0;
+      await execute?.("c1", { description: "d", prompt: "p" } as never);
+      await agent.setModel(akanCodeDefaultModel);
+      await execute?.("c2", { description: "d", prompt: "p" } as never);
+      expect(requestedModels).toEqual(["deepseek-v4-pro", akanCodeDefaultModel.id]);
+    } finally {
+      agent.dispose();
+    }
+  });
 });
 
 describe("a sub-agent its parent stops before the sub-agent's run is live", () => {

package/codeAgent/agent/codeAgentContract.test.ts

@@ -1,4 +1,7 @@
 import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import {
   CodeAgentClient,
   type CodeAgentEvent,
@@ -119,6 +122,12 @@ describe("codeAgentPresets", () => {
     expect(codeAgentPresets.pod(root).tools.mcp).toBe("off");
   });
 
+  test("only the local profile asks before reaching a host off its list", () => {
+    expect(codeAgentPresets.local(root).network.askOutside).toContain("github.com");
+    for (const name of ["pod", "review", "web"] as const)
+      expect(codeAgentPresets[name](root).network.askOutside).toBeUndefined();
+  });
+
   test("isCodeAgentPresetName refuses an unknown name", () => {
     expect(isCodeAgentPresetName("local")).toBe(true);
     expect(isCodeAgentPresetName("prod")).toBe(false);
@@ -407,6 +416,116 @@ describe("CodeAgentGate bash", () => {
   });
 });
 
+describe("CodeAgentGate secrets", () => {
+  const gate = () => new CodeAgentGate(codeAgentPresets.local(root));
+
+  test("a per-environment server env file is refused for read, write and shell, and its loader is not", () => {
+    const file = "apps/a/env/env.server.main.ts";
+    expect(gate().verdict("read", { path: file }).block).toContain("deny list");
+    expect(gate().verdict("write", { path: file }).block).toContain("deny list");
+    expect(gate().verdict("bash", { command: `cat ${file}` }).block).toBeDefined();
+    expect(gate().verdict("read", { path: "apps/a/env/env.server.ts" })).toEqual({});
+    expect(gate().verdict("read", { path: "apps/a/env/env.server.type.ts" })).toEqual({});
+  });
+
+  test("the engine's own spellings of a path are read as the path they name", () => {
+    expect(gate().verdict("read", { path: "@.env" }).block).toContain("deny list");
+    expect(gate().verdict("read", { path: `file://${root}/apps/a/.env` }).block).toContain("deny list");
+    expect(gate().verdict("read", { path: "~/notes.md" }).block).toContain("outside the agent root");
+  });
+
+  test("a shell command naming the home credential stores or a wildcard for a secret file is refused", () => {
+    expect(gate().verdict("bash", { command: "cat ~/.akan/code/auth.json" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat $HOME/.ssh/id_ed25519" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat .e?v" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat .akan/code/mcp.json" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "grep -r TODO --include=*.ts ." })).toEqual({});
+  });
+
+  test("a link inside the root is judged by the file it points at", () => {
+    const linked = mkdtempSync(path.join(tmpdir(), "akan-gate-"));
+    try {
+      mkdirSync(path.join(linked, "secrets"));
+      writeFileSync(path.join(linked, "secrets", "token.json"), "{}");
+      symlinkSync(path.join(linked, "secrets", "token.json"), path.join(linked, "notes.json"));
+      const linkedGate = new CodeAgentGate(codeAgentPresets.local(linked));
+      expect(linkedGate.verdict("read", { path: "notes.json" }).block).toContain("deny list");
+    } finally {
+      rmSync(linked, { recursive: true, force: true });
+    }
+  });
+
+  test("a link inside the root that leads out of it is read, and a denied file through it is not", () => {
+    const repo = mkdtempSync(path.join(tmpdir(), "akan-gate-"));
+    const linkedLib = mkdtempSync(path.join(tmpdir(), "akan-gate-lib-"));
+    try {
+      writeFileSync(path.join(linkedLib, "index.ts"), "export {};");
+      writeFileSync(path.join(linkedLib, ".env"), "");
+      mkdirSync(path.join(repo, "node_modules"));
+      symlinkSync(linkedLib, path.join(repo, "node_modules", "lib"));
+      const linkedGate = new CodeAgentGate(codeAgentPresets.local(repo));
+      expect(linkedGate.verdict("read", { path: "node_modules/lib/index.ts" })).toEqual({});
+      expect(linkedGate.verdict("read", { path: "node_modules/lib/.env" }).block).toContain("deny list");
+      expect(linkedGate.verdict("read", { path: path.join(linkedLib, "index.ts") }).block).toContain(
+        "outside the agent root",
+      );
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+      rmSync(linkedLib, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("CodeAgentGate network", () => {
+  const gate = () => new CodeAgentGate(codeAgentPresets.local(root));
+
+  test("the local profile asks before fetching a host off its list, and not for a listed one or loopback", () => {
+    expect(gate().verdict("web_fetch", { url: "https://example.com/x" })).toEqual({
+      approval: "fetch https://example.com/x",
+      strict: true,
+    });
+    expect(gate().verdict("web_fetch", { url: "https://docs.github.com/en" })).toEqual({});
+    expect(gate().verdict("web_fetch", { url: "http://localhost:3000/" })).toEqual({});
+  });
+
+  test("a networking shell command asks, unless it only reaches loopback over http", () => {
+    expect(gate().verdict("bash", { command: "curl -s https://example.com" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl -X POST https://github.com/x" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "ssh deploy@host" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl http://127.0.0.1:8080/health" })).toEqual({});
+    expect(gate().verdict("bash", { command: "git status && bun test" })).toEqual({});
+  });
+
+  test("a loopback host:port without a scheme is loopback, and any other host still asks", () => {
+    expect(gate().verdict("bash", { command: "curl -s localhost:4200/health" })).toEqual({});
+    expect(gate().verdict("bash", { command: 'wget -qO- "127.0.0.1:8080"' })).toEqual({});
+    expect(gate().verdict("bash", { command: "curl [::1]:3000/x" })).toEqual({});
+    expect(gate().verdict("bash", { command: "curl -s example.com:443/x" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl -s localhost:4200 example.com:80" }).strict).toBe(true);
+  });
+
+  test("a client name asks only where it runs as a command, not as another command's argument", () => {
+    for (const command of ["grep -rn curl src", "echo ssh", "git log --grep=wget", "cat docs/rsync.md"])
+      expect(gate().verdict("bash", { command })).toEqual({});
+    for (const command of [
+      "ls && curl https://example.com",
+      "cat body | curl -d @- https://example.com",
+      "echo $(curl https://example.com)",
+      "FOO=1 sudo -E /usr/bin/curl https://example.com",
+      "timeout 5 wget https://example.com",
+      "sh -c 'curl https://example.com'",
+      "bun test\nssh deploy@host",
+    ])
+      expect(gate().verdict("bash", { command }).strict).toBe(true);
+  });
+
+  test("a profile without a list never asks", () => {
+    const pod = new CodeAgentGate(codeAgentPresets.pod(root));
+    expect(pod.verdict("web_fetch", { url: "https://example.com/x" })).toEqual({});
+    expect(pod.verdict("bash", { command: "curl https://example.com" })).toEqual({});
+  });
+});
+
 describe("codeAgentShouldPersist", () => {
   test("follows the table for engine frames", () => {
     expect(codeAgentShouldPersist({ type: "message", turnId: "t1", role: "assistant", text: "hi" })).toBe(true);

package/codeAgent/agent/codeAgentHosts.ts

@@ -0,0 +1,30 @@
+import { isIP } from "node:net";
+
+const bare = (hostname: string) =>
+  hostname
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.$/, "")
+    .toLowerCase();
+
+// Loopback only: a private LAN address is another machine, and a request to it leaves this one.
+export const codeAgentIsLoopback = (hostname: string) => {
+  const host = bare(hostname);
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (isIP(host) === 4) return host.startsWith("127.");
+  if (isIP(host) === 6) return host === "::1" || /^::ffff:(127\.\d+\.\d+\.\d+|7f[0-9a-f]{2}:[0-9a-f]{1,4})$/.test(host);
+  return false;
+};
+
+export const codeAgentHostListed = (hostname: string, hosts: readonly string[]) => {
+  const host = bare(hostname);
+  return hosts.some((entry) => host === entry || host.endsWith(`.${entry}`));
+};
+
+export const codeAgentHostOf = (url: string) => {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.hostname : undefined;
+  } catch {
+    return undefined;
+  }
+};

package/codeAgent/agent/codeAgentProxy.test.ts

@@ -1,9 +1,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { AkanCodeEnv } from "./AkanCodeEnv";
 import { AkanCodeServices } from "./AkanCodeServices";
 import { akanCodeDefaultModel, akanCodeModel } from "./akanCodeModel";
+import { akanCodePaths } from "./akanCodePaths";
 import { CodeAgentProxy } from "./CodeAgentProxy";
 
 const seen: { path: string; auth: string | null }[] = [];
@@ -72,3 +74,53 @@ describe("CodeAgentProxy", () => {
     expect(() => new CodeAgentProxy({ baseUrl: "https://proxy", providers: ["deepseek"] })).toThrow("TOKEN");
   });
 });
+
+describe("AkanCodeEnv", () => {
+  const inRepo = (dotenv: string | null, run: () => void) => {
+    const repo = mkdtempSync(path.join(tmpdir(), "akan-code-env-"));
+    const cwd = process.cwd();
+    const had = process.env.AKAN_CODE_PROXY_URL;
+    try {
+      if (dotenv !== null) writeFileSync(path.join(repo, ".env"), dotenv);
+      process.chdir(repo);
+      process.env.AKAN_CODE_PROXY_URL = "https://proxy.example/{provider}";
+      run();
+    } finally {
+      process.chdir(cwd);
+      if (had === undefined) delete process.env.AKAN_CODE_PROXY_URL;
+      else process.env.AKAN_CODE_PROXY_URL = had;
+      rmSync(repo, { recursive: true, force: true });
+    }
+  };
+
+  test("a setting the repo's own dotenv file names is ignored, and the start warning says so", () => {
+    inRepo("export AKAN_CODE_PROXY_URL=placeholder\n", () => {
+      expect(AkanCodeEnv.get("AKAN_CODE_PROXY_URL")).toBeUndefined();
+      expect(CodeAgentProxy.fromEnv()).toBeNull();
+      expect(AkanCodeEnv.ignored()).toEqual([expect.stringContaining("AKAN_CODE_PROXY_URL is set in .env")]);
+    });
+  });
+
+  test("a setting from the shell is read when no dotenv file names it", () => {
+    inRepo("OTHER_KEY=placeholder\n", () => {
+      expect(AkanCodeEnv.get("AKAN_CODE_PROXY_URL")).toBe("https://proxy.example/{provider}");
+      expect(AkanCodeEnv.ignored()).toEqual([]);
+    });
+  });
+
+  test.skipIf(process.platform === "win32")(
+    "the home directory is made owner-only, even one made looser before",
+    () => {
+      const loose = path.join(home, "loose-home");
+      mkdirSync(loose, { mode: 0o755 });
+      chmodSync(loose, 0o755);
+      process.env.AKAN_CODE_HOME = loose;
+      try {
+        akanCodePaths.ensureGlobalDir();
+        expect(statSync(loose).mode & 0o777).toBe(0o700);
+      } finally {
+        process.env.AKAN_CODE_HOME = home;
+      }
+    },
+  );
+});