docs(permissions): clarify project-layer scope and log canonical grant-file path

Author: TheGreatAxios

docs/IMPLEMENTATION.md

@@ -321,7 +321,7 @@ Provider and model configuration lives in JSON settings files. The global file h
 
 - Per-repo: `.corbits/settings.json` — **selection only**, e.g. `{ "provider": "firepass", "model": "fp-small" }`. Any other key (notably `apiKey` or `baseURL`) is rejected by the loader, and the file is gitignored. It is also on the secret-guard denylist for path-keyed tools, as is the global file, so the agent cannot `read_file` its own credentials (shell references still require explicit operator approval). The project grant store (`.corbits/permissions.json`) is on the same denylist so the agent cannot write a standing auto-approval. An unconfirmed project file still contributes no grants.
 
-  `corbits exec --permissions <path>` replaces the user-global and provider-model grants for that process only. The file is `{ "approvals": [ { "tool": "run_shell", "pattern": "bun install*" } ] }` (`providerModel` optional). It is not merged with `~/.corbits/permissions.json` and is not a settings key. A missing `approvals` key is an empty replacement; a `providerModels` map in that file is not applied. Session grants stay in memory and project grants still use the project permissions file. While the flag is set, global and provider-model Allow Always append to that file's `approvals` array, and `/permissions` revoke removes the row from it. Neither path reads or writes `~/.corbits/permissions.json`. A missing, unreadable, or invalid file, or a wildcard-only pattern, fails at start.
+  `corbits exec --permissions <path>` replaces the user-global and provider-model grants for that process only. The file is `{ "approvals": [ { "tool": "run_shell", "pattern": "bun install*" } ] }` (`providerModel` optional). It is not merged with `~/.corbits/permissions.json` and is not a settings key. A missing `approvals` key is an empty replacement; a `providerModels` map in that file is not applied. Session grants stay in memory and project grants still use the project permissions file. While the flag is set, global and provider-model Allow Always append to that file's `approvals` array, and `/permissions` revoke removes the row from it. Neither path reads or writes `~/.corbits/permissions.json`. A missing, unreadable, or invalid file, or a wildcard-only pattern, fails at start. Every load (startup validation, seed, `/permissions` reseed) logs the canonical realpath target and approval count.
 
   `baseURL` is editable provider metadata, but it still belongs in the global provider definition rather than the per-repo selection file. `apiKey` is secret and must never be projected into TUI display-only provider lists.
 

src/config/index.ts

@@ -622,7 +622,8 @@ export interface Config {
   /**
    * Absolute path from `--permissions`. When set, that file's approvals
    * replace the user-global and provider-model grant lists for this process
-   * only. Not a settings key.
+   * only. Session and project layers still apply, and project-file entries
+   * still need trust confirmation. Not a settings key.
    */
   permissionsPath?: string;
   globalDefaultProvider?: string;
@@ -733,7 +734,9 @@ Continue verbs (project-keyed to this checkout's git toplevel):
 Flags:
   --cwd <dir>                 working directory (default: process.cwd())
   --config <path>             settings file (default: ~/.corbits/settings.json)
-  --permissions <path>        grant file replacing ~/.corbits/permissions.json for this process
+  --permissions <path>        grant file replacing global + provider-model grants
+                               for this process only (session + project layers still
+                               apply; project entries still need trust confirmation)
   --provider <name>           configured provider name
   --model <id>                model for the active provider
   --profile <name>            settings profile

src/permission/permissions-file.test.ts

@@ -0,0 +1,94 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getLogger } from "@intx/log";
+
+import { LOG_NAMESPACE_ROOT } from "../branding.js";
+import { canonicalGrantFilePath, loadPermissionsFile } from "./store.js";
+
+const grantsFileLog = getLogger([
+  LOG_NAMESPACE_ROOT,
+  "permission",
+  "grants-file",
+]);
+
+describe("grant-file canonical logging", () => {
+  let dir = "";
+
+  beforeEach(() => {
+    spyOn(grantsFileLog, "info");
+  });
+
+  afterEach(async () => {
+    mock.restore();
+    if (dir !== "") await rm(dir, { recursive: true, force: true });
+    dir = "";
+  });
+
+  test("loading through a symlink logs the canonical realpath target", async () => {
+    dir = await mkdtemp(join(tmpdir(), "grants-file-"));
+    const target = join(dir, "grants.json");
+    await writeFile(
+      target,
+      JSON.stringify({
+        approvals: [
+          { tool: "run_shell", pattern: "bun install*" },
+          {
+            tool: "run_shell",
+            pattern: "scoped cargo *",
+            providerModel: "openai:gpt-5",
+          },
+        ],
+      }),
+    );
+    const link = join(dir, "link.json");
+    await symlink(target, link);
+
+    const approvals = await loadPermissionsFile(link);
+
+    expect(approvals).toHaveLength(2);
+    expect(grantsFileLog.info).toHaveBeenCalledWith(
+      "Grant file loaded: {path} ({count} approvals)",
+      { path: await realpath(link), count: 2 },
+    );
+  });
+
+  test("a file without an approvals key logs an empty load", async () => {
+    dir = await mkdtemp(join(tmpdir(), "grants-file-"));
+    const path = join(dir, "grants.json");
+    await writeFile(path, JSON.stringify({}));
+
+    const approvals = await loadPermissionsFile(path);
+
+    expect(approvals).toEqual([]);
+    expect(grantsFileLog.info).toHaveBeenCalledWith(
+      "Grant file loaded: {path} ({count} approvals)",
+      { path: await realpath(path), count: 0 },
+    );
+  });
+
+  test("a missing file fails closed without a load log", async () => {
+    dir = await mkdtemp(join(tmpdir(), "grants-file-"));
+
+    await expect(
+      loadPermissionsFile(join(dir, "missing.json")),
+    ).rejects.toThrow(/not found/);
+    expect(grantsFileLog.info).not.toHaveBeenCalled();
+  });
+
+  test("canonicalGrantFilePath falls back to the given path when unreadable", async () => {
+    dir = await mkdtemp(join(tmpdir(), "grants-file-"));
+    const missing = join(dir, "missing.json");
+
+    await expect(canonicalGrantFilePath(missing)).resolves.toBe(missing);
+  });
+});

src/permission/store.ts

@@ -1,13 +1,14 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import { type } from "arktype";
+import { getLogger } from "@intx/log";
 
 import type { Approval } from "./types.js";
 import { sessionDir } from "../session/index.js";
-import { SETTINGS_DIR_NAME } from "../branding.js";
+import { LOG_NAMESPACE_ROOT, SETTINGS_DIR_NAME } from "../branding.js";
 import {
   isProjectGrantTrusted,
   reconcileProjectGrants,
@@ -300,6 +301,24 @@ export async function loadProviderModelApprovals(
 // unreadable, and invalid files must fail closed: the persisted-store readers
 // treat ENOENT as an empty list and drop bad entries, which would silently
 // change the caller's grant set.
+const grantsFileLog = getLogger([
+  LOG_NAMESPACE_ROOT,
+  "permission",
+  "grants-file",
+]);
+
+// The canonical grant-file target for logs: a symlinked --permissions path
+// and its target must not read as two different grant sources. Falls back to
+// the given path when the file is missing or unreadable — the load below
+// still fails closed with its own error.
+export async function canonicalGrantFilePath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return path;
+  }
+}
+
 export async function loadPermissionsFile(path: string): Promise<Approval[]> {
   let raw: string;
   try {
@@ -322,8 +341,16 @@ export async function loadPermissionsFile(path: string): Promise<Approval[]> {
     throw new Error(`--permissions file must be a JSON object: ${path}`);
   }
   const approvals = (parsed as Record<string, unknown>).approvals;
-  if (approvals === undefined) return [];
-  return parseApprovalList(approvals, path);
+  // Startup, seed, and every /permissions reseed funnel through here, so one
+  // log line names the active grant source for the whole process lifetime.
+  const canonicalPath = await canonicalGrantFilePath(path);
+  const list =
+    approvals === undefined ? [] : parseApprovalList(approvals, path);
+  grantsFileLog.info("Grant file loaded: {path} ({count} approvals)", {
+    path: canonicalPath,
+    count: list.length,
+  });
+  return list;
 }
 
 // The process grant list is either the --permissions file or the user stores.