@bevel-software/platform-core-backend 0.28.1 → 0.29.0

package/src/modules/embed/embed.service.ts

@@ -1,6 +1,5 @@
 import { createHmac } from 'node:crypto';
-import { timingSafeStringEqual } from '../auth/password-hash.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/account-admission.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, timingSafeStringEqual } from '../auth/index.js';
 import jwt from 'jsonwebtoken';
 import type { AuthUser, IGitService, IWorkflowService } from '@bevel-software/platform-shared';
 import { suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
@@ -8,9 +7,9 @@ import { logger } from '../../shared/logging.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { changeRequestLink, changeRequestLinkBase } from '../workflow/git/change-request-link.js';
-import type { FileReaderRegistry } from '../workspace/file-readers/file-reader.js';
-import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
+import { changeRequestLink, changeRequestLinkBase } from '../workflow/index.js';
+import type { FileReaderRegistry } from '../workspace/index.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 import type {
   EmbedAuthPort,
   EmbedFileView,
@@ -21,6 +20,7 @@ import type {
   EmbedProposalResult,
   EmbedSubject,
   EmbedTokenResult,
+  EmbedViewer,
   IEmbedService,
 } from './embed.interface.js';
 import {
@@ -35,16 +35,24 @@ import type { IAccountLinkService } from './account-link.service.js';
 const log = logger('embed');
 
 /**
- * Token lifetime — long enough for a view left open in a chat, short enough
- * that a token copied out of a transcript stops working on its own. The
- * token rides in `open_page`'s result, so it sits in the chat transcript, and
- * whoever holds it reads and edits that one file as the token's user until
- * it expires. One hour (Razvan, 2026-10-09; the embed used two before): a
- * page left open in a chat is still covered, and the window is halved. A
- * view older than that shows the expired sentence and the agent opens the
- * page again.
+ * Lifetime of a token `open_page` mints (`kind: user`). The token rides in
+ * the tool's result, so it sits in the chat transcript, and whoever holds it
+ * reads and edits that one file as the token's user until it expires. Five
+ * minutes (Razvan, 2026-10-09; one hour before, two before that): a token
+ * copied out of a transcript stops working almost at once. A view left open
+ * longer is not ended by it — the MCP App view asks its host to call
+ * `open_page` again when a call is refused for the token, and carries on with
+ * the fresh one (see `mcp-app/page.html`).
  */
-export const EMBED_TOKEN_TTL_SECONDS = 60 * 60;
+export const EMBED_USER_TOKEN_TTL_SECONDS = 5 * 60;
+
+/**
+ * Lifetime of a token the Atlassian connector mints through the shared-secret
+ * route (`kind: atlassian`). One hour, unchanged: the connector frames
+ * `/embed` directly and has no host to renew a token through, and its mint
+ * contract does not change (Decision 9 of the parent specification).
+ */
+export const EMBED_CONNECTOR_TOKEN_TTL_SECONDS = 60 * 60;
 
 /** What the embed's config needs from the deployment's. */
 export interface EmbedConfig {
@@ -148,7 +156,11 @@ export class EmbedService implements IEmbedService {
     if (!this.authService.isEmailDomainAllowed(email ?? '')) {
       throw new EmbedAccessError('Your email domain is not permitted to view this content');
     }
-    return this.mint({ kind: 'atlassian', accountId: input.accountId }, input.reference);
+    const minted = await this.mint({ kind: 'atlassian', accountId: input.accountId }, input.reference);
+    // The connector's host sizes its frame to the content (the issue panel
+    // grows with the page), so its view is told to report its height; the
+    // MCP path says nothing, and its host's fixed reading pane stays.
+    return { ...minted, embedUrl: this.embedUrlFor(minted.token, { sizing: 'content' }) };
   }
 
   /**
@@ -195,13 +207,20 @@ export class EmbedService implements IEmbedService {
       repoRelative,
       slug: ref.slug,
     };
-    const token = jwt.sign(claims, this.signingKey, { expiresIn: EMBED_TOKEN_TTL_SECONDS });
+    const expiresIn =
+      subject.kind === 'user' ? EMBED_USER_TOKEN_TTL_SECONDS : EMBED_CONNECTOR_TOKEN_TTL_SECONDS;
+    const token = jwt.sign(claims, this.signingKey, { expiresIn });
     return { token, embedUrl: this.embedUrlFor(token) };
   }
 
-  /** The view's address — what a host frames. */
-  embedUrlFor(token: string): string {
-    return `${this.config.publicFrontendUrl}/embed?token=${encodeURIComponent(token)}`;
+  /**
+   * The view's address — what a host frames. `sizing: 'content'` tells the
+   * view its host sizes the frame to the content and wants the height
+   * reported; absent, the host's fixed pane is kept.
+   */
+  embedUrlFor(token: string, opts: { sizing?: 'content' } = {}): string {
+    const sizing = opts.sizing === 'content' ? '&sizing=content' : '';
+    return `${this.config.publicFrontendUrl}/embed?token=${encodeURIComponent(token)}${sizing}`;
   }
 
   /** A file's address in the app — what a link opens in a new tab. */
@@ -556,6 +575,12 @@ export class EmbedService implements IEmbedService {
     return { claims, user, wsPath: this.wsPathFor(claims.repoRelative) };
   }
 
+  async viewerOf(token: string): Promise<EmbedViewer> {
+    const claims = this.verifyToken(token);
+    const identity = await this.resolveIdentity(claims);
+    return { ...identity, repoRelative: claims.repoRelative };
+  }
+
   /** Resolve the token's identity to a user + read/write verdicts. */
   private async resolveIdentity(claims: EmbedClaims): Promise<ResolvedIdentity> {
     const unresolved: ResolvedIdentity = { linked: false, user: null, canRead: false, canWrite: false };

package/src/modules/embed/embed.tools.ts

@@ -104,6 +104,10 @@ export function registerEmbedTools(
       type: 'object',
       properties: {
         path: { type: 'string', description: 'The path that was shown (echoes the input).' },
+        heading: {
+          type: 'string',
+          description: 'The heading the view opens at (echoes the input). Absent when none was named.',
+        },
         content: { type: 'string', description: "The page's text, exactly as `read_file` answers it." },
         embedUrl: {
           type: 'string',
@@ -163,12 +167,16 @@ export function registerEmbedTools(
         result.kind === 'text' ? result.text : result.kind === 'image' ? result.note : result.message;
 
       const appUrl = deps.appUrlFor(repoRelative, heading);
+      // The heading goes back beside the path: the view calls this tool again
+      // with both when its token runs out (see `mcp-app/page.html`), and a
+      // result is all it is told.
+      const echoed = heading ? { heading } : {};
       // No view on a plain-http deployment (Decision 8): a host's https
       // sandbox cannot load from it. The text and the app address are still
       // the answer, and the tool says why there is no view rather than
       // handing back an address no host can open.
       if (!deps.canBeReached()) {
-        return { path: raw, content, appUrl, branch, note: HTTP_DEPLOYMENT_NOTE };
+        return { path: raw, ...echoed, content, appUrl, branch, note: HTTP_DEPLOYMENT_NOTE };
       }
       // Minted for the identity THIS MCP session authenticated — the
       // signed-in user, or the owner of the connection key the agent carries.
@@ -178,7 +186,7 @@ export function registerEmbedTools(
         userId: ctx.user.id,
         reference: heading ? `${repoRelative}#${heading}` : repoRelative,
       });
-      return { path: raw, content, embedUrl, appUrl, branch };
+      return { path: raw, ...echoed, content, embedUrl, appUrl, branch };
     }),
   );
 }

package/src/modules/kb-fs/index.ts

@@ -0,0 +1,6 @@
+/**
+ * What the kb-fs module offers the other modules. The filesystem and the
+ * locks are wired by the composition root; a module that writes through the
+ * workspace needs only the shape of the gate every write passes first.
+ */
+export type { WriteValidator } from './locking-filesystem.js';

package/src/modules/plugins/__tests__/join-request-jobs.service.test.ts

@@ -1,11 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
-import {
-  PluginJoinRequestJobs,
-  JoinRequestNotReadyError,
-  type JoinRequestJobsDeps,
-  CLAIM_STALE_AFTER_MS,
-} from '../join-request-jobs.service.js';
+import { DrizzleQueryError } from 'drizzle-orm';
+import { PluginJoinRequestJobs, JoinRequestNotReadyError, type JoinRequestJobsDeps } from '../index.js';
+// The claim window is not part of the module's surface: a test that moves
+// the clock past it reads the number the service itself uses.
+import { CLAIM_STALE_AFTER_MS } from '../join-request-jobs.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { FakeJoinRequestStore } from './fake-join-request-store.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -146,6 +145,48 @@ describe('PluginJoinRequestJobs', () => {
     expect(row.failureReason).not.toContain('ghp_secret');
   });
 
+  it("logs a database failure as the database's reason, and shows the requester one stable sentence", async () => {
+    const h = harness();
+    // What Drizzle throws: its own error class, the SQL in the message, the
+    // driver's error as the cause.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new DrizzleQueryError(
+        'insert into "change_requests" ("id", "number", "title", "body", "source_branch", "target_branch", "author_id", "status", "created_at", "updated_at") values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)',
+        [],
+        new Error('relation "change_requests" does not exist'),
+      ),
+    );
+    await h.jobs.start(pendingRow(h.store));
+
+    // The operator gets the reason, not the wrapper's cut-off SQL…
+    const logged = consoleError.mock.calls.map((c) => String(c[0]));
+    // (`printable` renders the reason as a JSON string, so its own quotes come escaped.)
+    expect(logged).toContainEqual(expect.stringMatching(/failed: "relation \\"change_requests\\" does not exist"/));
+    expect(logged.some((l) => l.includes('Failed query'))).toBe(false);
+    // …and the requester's card names no table.
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toBe('the request could not be recorded; an admin can find the reason in the server log');
+  });
+
+  it("shows the requester a wrapped failure's own words when it is not the database's", async () => {
+    const h = harness();
+    // The git work failing behind a wrapper of its own: the cause is what is
+    // logged, and what the requester reads, credentials stripped — the
+    // database's stable sentence would hide the detail they can act on.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new Error('opening the change request failed', {
+        cause: new Error('fatal: unable to access https://x:ghp_secret@github.com/acme/kb: could not resolve host'),
+      }),
+    );
+    await h.jobs.start(pendingRow(h.store));
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toContain('unable to access');
+    expect(row.failureReason).not.toContain('ghp_secret');
+    expect(row.failureReason).not.toContain('could not be recorded');
+  });
+
   it('fails the record rather than throwing when the plugin is gone', async () => {
     const h = harness({ target: async () => null });
     await expect(h.jobs.start(pendingRow(h.store))).resolves.toBeUndefined();
@@ -524,6 +565,32 @@ describe('PluginJoinRequestJobs', () => {
     expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
   });
 
+  it("a sweep that cannot read the table logs the database's reason, not the wrapper's cut-off SQL", async () => {
+    vi.useFakeTimers();
+    const warned = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const h = harness();
+      // What Drizzle throws: its own error class, the SQL in the message, the driver's error underneath.
+      const wrapped = new DrizzleQueryError(
+        'select "id", "requester_email", "requester_email_bidx", "requester_name", "plugin_key", "status", "failure_reason", "change_request_number", "claimed_at", "claim_token", "created_at" from "plugin_join_requests" where status = $1',
+        [],
+        new Error('Cannot use a pool after calling end on the pool'),
+      );
+      h.store.pending = async () => {
+        throw wrapped;
+      };
+      h.jobs.startSweeping(1000);
+      await vi.advanceTimersByTimeAsync(0);
+      h.jobs.stopSweeping();
+      const lines = warned.mock.calls.map((c) => String(c[0]));
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('could not look at the join requests still owed: "Cannot use a pool after calling end on the pool"');
+      expect(lines[0]).not.toContain('Failed query');
+    } finally {
+      warned.mockRestore();
+    }
+  });
+
   it('proceeds past a createBranch failure only when the branch is really there', async () => {
     const h = harness();
     const branch = joinBranchFor(ALI, 'Finance');

package/src/modules/plugins/join-request-jobs.service.ts

@@ -4,6 +4,7 @@ import {
   type ChangeRequestState,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
+import { DrizzleQueryError } from 'drizzle-orm';
 import { spliceGrant } from '../access-model/access-splice.js';
 import { sanitizeError } from '../workflow/sanitize-error.js';
 import { logger } from '../../shared/logging.js';
@@ -358,12 +359,12 @@ export class PluginJoinRequestJobs {
    */
   startSweeping(intervalMs: number = SWEEP_INTERVAL_MS): void {
     void this.sweep().catch((err: unknown) => {
-      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
     });
     if (this.sweepTimer) return;
     this.sweepTimer = setInterval(() => {
       void this.sweep().catch((err: unknown) => {
-        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
       });
     }, intervalMs);
     // Never a reason for the process to stay alive: every row is durable, and
@@ -398,7 +399,7 @@ export class PluginJoinRequestJobs {
     // wrap the whole attempt: the claim has to be refreshed for as long as
     // the work runs, and the work is the part that can take minutes.
     const live = await this.store.claim(record.id, CLAIM_STALE_AFTER_MS).catch((err: unknown) => {
-      log.warn(`could not claim a join request: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not claim a join request: ${loggable(sanitizeError(underlying(err)))}`);
       return null;
     });
     if (!live) {
@@ -426,7 +427,7 @@ export class PluginJoinRequestJobs {
         if (!still) held = false;
         return still ? 'held' : 'lost';
       } catch (err: unknown) {
-        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(underlying(err)))}`);
         return 'unknown';
       }
     };
@@ -453,7 +454,10 @@ export class PluginJoinRequestJobs {
         if (state !== 'held') throw new ClaimLostError(state);
       });
     } catch (err) {
-      const reason = sanitizeError(err);
+      // The cause when there is one (see `underlying`), for the log; a
+      // database's reason, where a wrapper's cut-off column list is not.
+      const cause = underlying(err);
+      const reason = sanitizeError(cause);
       // `pluginKey` is a persisted folder path, so it is escaped before it
       // reaches a log line: a folder carrying control characters could
       // otherwise write newlines of its own into the log.
@@ -473,22 +477,31 @@ export class PluginJoinRequestJobs {
         // claim held by a process that never really started.
         log.warn(`join request for ${key} postponed: ${loggable(reason)}`);
         await this.store.release(record.id, live.claimToken).catch((releaseErr: unknown) => {
-          log.warn(`could not release that claim: ${loggable(sanitizeError(releaseErr))}`);
+          log.warn(`could not release that claim: ${loggable(sanitizeError(underlying(releaseErr)))}`);
         });
         return;
       }
       log.error(`join request for ${key} failed: ${loggable(reason)}`);
+      // What the requester reads on their card. The git work's own words
+      // are theirs to see (credentials stripped); a database's reason is
+      // not — it names tables and columns and is for the operator, who has
+      // it in the line above — so a database failure is recorded in one
+      // stable sentence. The database's failures are the ones the query
+      // layer wraps (`DrizzleQueryError`, its cause the driver's error);
+      // any other wrapped error keeps its own sanitised words, which may be
+      // what the requester needs to act on.
+      const shown = err instanceof DrizzleQueryError ? DATABASE_FAILURE_REASON : reason;
       await this.store
         // Named with the token, so this lands only if the row is still this
         // process's. A worker that overran the window and had its row taken
         // writes nothing here rather than stamping its failure on the attempt
         // that replaced it — which would show the requester a failure for
         // work that is, at that moment, succeeding.
-        .markFailed(record.id, live.claimToken, reason)
+        .markFailed(record.id, live.claimToken, shown)
         // Nothing left to do if even that write fails: the row stays
         // `pending` and the next boot's sweep tries the whole thing again.
         .catch((writeErr: unknown) => {
-          log.error(`could not record that failure: ${loggable(sanitizeError(writeErr))}`);
+          log.error(`could not record that failure: ${loggable(sanitizeError(underlying(writeErr)))}`);
         });
     } finally {
       held = false;
@@ -669,6 +682,30 @@ function loggable(reason: string): string {
   return printable(reason);
 }
 
+/**
+ * The error behind a wrapped one. Drizzle reports a failed query as its own
+ * error whose message is the SQL and whose `cause` is the database's reason;
+ * the sanitizer caps a message at a couple of hundred characters, so logging
+ * the wrapper showed a cut-off column list and never the reason. The reason
+ * is what every LOG line this service writes needs — "the pool has been
+ * ended", "relation does not exist" — the sweep's warning, the claim and
+ * heartbeat warnings, the failure line. The requester's card is the one
+ * place it does not go: a wrapped failure is recorded there as
+ * `DATABASE_FAILURE_REASON`, since a table name is the operator's to read.
+ * An error with no cause (git's, the claim's own) is reported as it is.
+ */
+function underlying(err: unknown): unknown {
+  const cause = typeof err === 'object' && err !== null ? (err as { cause?: unknown }).cause : undefined;
+  return cause instanceof Error ? cause : err;
+}
+
+/**
+ * The sentence a requester's card carries when the database, not the git
+ * work, refused the request: stable, and naming no table or column. The
+ * database's own words go to the server log beside it.
+ */
+const DATABASE_FAILURE_REASON = 'the request could not be recorded; an admin can find the reason in the server log';
+
 /** Node's "there is no such file" errors, and only those. */
 function isFileAbsent(err: unknown): boolean {
   const code = (err as NodeJS.ErrnoException | null)?.code;

package/src/modules/skills/__tests__/branch-skills.tools.test.ts

@@ -154,7 +154,7 @@ describe('the skill tools read a branch when asked', () => {
       skills: { name: string; unmerged?: boolean }[];
     };
     expect(listArgs).toEqual([['e@x', { branch: undefined }]]);
-    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path }]);
+    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path, canWrite: false }]);
   });
 
   it('a blank branch is no branch at all: the released catalog answers', async () => {

package/src/modules/skills/skills.contract.ts

@@ -52,6 +52,10 @@ export interface SkillSummary {
   unmerged?: true;
   /** With `unmerged`: the branch the skill was read from. */
   branch?: string;
+  // No `canWrite` here, on purpose: whether the caller may change a skill
+  // directly is a per-caller verdict the agent tools add onto a COPY of each
+  // summary (`skills.tools.ts`). The catalog is cached across users, so a
+  // verdict stored on it would be served to the next caller.
 }
 
 export interface Skill extends SkillSummary {

package/src/modules/skills/skills.tools.ts

@@ -10,6 +10,7 @@ import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { ISkillService } from './skills.contract.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
+import { CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts, type DefaultBranchWriteDeps } from '../tool-helpers/index.js';
 
 /**
  * The optional `branch` both skill tools declare. Optional on purpose, unlike
@@ -82,7 +83,57 @@ export function registerSkillsTools(
   skillService: ISkillService,
   /** When given, a loaded skill carries `warnings` for `allowed-tools` entries that name no visible tool. */
   allowedTools?: IAllowedToolsChecker,
+  /**
+   * Where `canWrite` is judged: the access layer and the default branch's
+   * workspace. Without it every verdict is `false` — the safe answer, which
+   * sends the agent to a change request rather than a direct write.
+   */
+  writeVerdicts?: DefaultBranchWriteDeps,
 ): void {
+  /**
+   * Whether the caller may commit each repo-relative path directly on the
+   * default branch — one batch per call, whichever branch was read (see
+   * `defaultBranchWriteVerdicts`).
+   */
+  const verdictsFor = (ctx: ToolContext, paths: string[], at?: string): Promise<Map<string, boolean>> =>
+    writeVerdicts
+      ? defaultBranchWriteVerdicts(writeVerdicts, ctx, paths, { ref: at })
+      : Promise.resolve(new Map(paths.map((p) => [p, false])));
+
+  /**
+   * Every repo-relative file `get_skill`'s `canWrite` covers: the skill's
+   * folder as COMMITTED on the default branch (`HEAD` of its clone), which is
+   * what a direct write is judged against — never the working tree, where a
+   * bundled file deleted but not yet committed would drop out of the verdict
+   * while `HEAD` still forbids changing it. A skill is committed there when
+   * its `SKILL.md` is — a folder of that name holding other tracked files is
+   * not the skill, and its files are not the skill's. A skill not committed
+   * there exists only on the branch read, and is judged by its files there,
+   * where they would land. The files are listed at ONE commit — the one
+   * `HEAD` names when asked, answered beside them — and the verdict is judged
+   * at that same commit, so a commit landing between the two cannot pair one
+   * snapshot's files with another's rules. Null — judged `false` — when
+   * `HEAD` names no commit or the listing fails (fail closed), and without
+   * one when the verdict cannot be anything but `false`.
+   */
+  const skillFilesOnDefault = async (
+    ctx: ToolContext,
+    loaded: { path: string; files: string[] },
+  ): Promise<{ paths: string[]; at: string } | null> => {
+    if (!writeVerdicts?.committedFiles || ctx.scope !== 'write') return null;
+    const workspaceId = writeVerdicts.defaultWorkspaceId();
+    let at: string | null;
+    let committed: string[];
+    try {
+      at = await writeVerdicts.committedFiles.commitAtRef(workspaceId, 'HEAD');
+      if (!at) return null;
+      committed = await writeVerdicts.committedFiles.listFilesAtRef(workspaceId, at, loaded.path);
+    } catch {
+      return null;
+    }
+    return { paths: committed.includes(skillMdOf(loaded)) ? committed : [skillMdOf(loaded), ...loaded.files], at };
+  };
+
   registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
@@ -96,9 +147,14 @@ export function registerSkillsTools(
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
-    toolHandler(async (args, ctx: ToolContext) => ({
-      skills: await skillService.listSkills(ctx.user.email, { branch: branchArg(args) }),
-    })),
+    toolHandler(async (args, ctx: ToolContext) => {
+      const skills = await skillService.listSkills(ctx.user.email, { branch: branchArg(args) });
+      // Judged on each skill's SKILL.md, by the default branch's rules — a
+      // skill only on a draft is judged where it would land. Each verdict goes
+      // onto a COPY: the summaries may be the catalog shared across users.
+      const verdicts = await verdictsFor(ctx, skills.map(skillMdOf));
+      return { skills: skills.map((s) => ({ ...s, canWrite: verdicts.get(skillMdOf(s)) === true })) };
+    }),
   );
 
   router.post(
@@ -114,7 +170,8 @@ export function registerSkillsTools(
       // skill's history, a `branch` is a draft nobody has released — asked for
       // together, neither answer is the one the caller meant, and guessing
       // would serve instructions under a label that does not describe them.
-      if (branch !== undefined && version !== undefined && version.trim().length > 0) {
+      const versioned = version !== undefined && version.trim().length > 0;
+      if (branch !== undefined && versioned) {
         throw new ToolError(
           'get_skill takes `branch` or `version`, not both: `branch` loads the skill as that draft has it ' +
             'now, `version` loads a version the released skill declared. Pass one of them.',
@@ -122,12 +179,33 @@ export function registerSkillsTools(
         );
       }
       const result = await skillService.getSkill(ctx.user.email, name, file, { version, branch });
-      if (!allowedTools || !result.ok || result.kind !== 'skill') return result;
-      return { ...result, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
+      if (!result.ok) return result;
+      if (result.kind === 'file') {
+        const verdicts = await verdictsFor(ctx, [result.file.path]);
+        return { ...result, file: { ...result.file, canWrite: verdicts.get(result.file.path) === true } };
+      }
+      // The whole skill: true only when every one of its files may be written —
+      // the files the skill has COMMITTED on the default branch, so a draft, an
+      // older version, or a deletion not yet committed that drops a
+      // write-denied bundled file does not turn the verdict true. A skill only
+      // on the draft is judged by its draft files, where they would land.
+      const committed = await skillFilesOnDefault(ctx, result.skill);
+      const verdicts = committed === null ? new Map<string, boolean>() : await verdictsFor(ctx, committed.paths, committed.at);
+      const skill = {
+        ...result.skill,
+        canWrite: committed !== null && committed.paths.every((p) => verdicts.get(p) === true),
+      };
+      if (!allowedTools) return { ...result, skill };
+      return { ...result, skill, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
     }),
   );
 }
 
+/** The repo-relative `SKILL.md` of a skill, which `list_skills` judges it by. */
+function skillMdOf(skill: { path: string }): string {
+  return `${skill.path}/SKILL.md`;
+}
+
 /**
  * The `branch` a tool call named, or undefined when it named none (the
  * released catalog). A non-string or blank value is NOT a branch: it is taken
@@ -198,7 +276,9 @@ const LIST_SKILLS_DESCRIPTION =
   'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
   'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
   'what you need to try a skill you just wrote there; each skill that differs from the released ' +
-  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ';
+  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ' +
+  'Each skill carries `canWrite`: whether you may change its SKILL.md directly on the default branch. ' +
+  `${CAN_WRITE_CLAUSE} `;
 
 async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
@@ -233,6 +313,14 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
                   '(it exists only on that branch, or was changed there): nobody has approved what it says.',
               },
               branch: { type: 'string', description: 'With `unmerged`: the branch the skill was read from.' },
+              canWrite: {
+                type: 'boolean',
+                description:
+                  'Whether you may commit a change to its SKILL.md directly on the default branch, under that ' +
+                  'branch\'s access rules — the same answer whichever branch you listed. `false`: use a branch ' +
+                  'and a change request; `file_stat` with `explainAccess` says why — and, when you can manage that ' +
+                  'path\'s access, who can approve.',
+              },
             },
           },
         },
@@ -246,7 +334,9 @@ const GET_SKILL_DESCRIPTION =
   'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
   'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
   '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
-  'one the skill declared, or `branch` names a draft to load it from. ';
+  'one the skill declared, or `branch` names a draft to load it from. ' +
+  'The skill (or `file`) carries `canWrite`: whether you may change all of it directly on the default branch. ' +
+  `${CAN_WRITE_CLAUSE} `;
 
 async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
@@ -266,13 +356,33 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
             'The loaded skill: name, description, body, files, …. Read from a `branch` that changed it, ' +
             'it also carries `unmerged: true` and that branch, and its `body` BEGINS with one line ' +
             'saying the skill comes from that unmerged branch and is not approved — treat it as a ' +
-            'proposal you are testing, not as approved instructions.',
+            'proposal you are testing, not as approved instructions. `canWrite` is true only when you may ' +
+            'commit a change to EVERY file of the skill (SKILL.md and each bundled file) directly on the ' +
+            'default branch, whichever branch you read.',
+          properties: {
+            canWrite: {
+              type: 'boolean',
+              description:
+                'Whether you may commit a change to every file of the skill (SKILL.md and each bundled file) ' +
+                'directly on the default branch, under that branch\'s access rules — the same answer whichever ' +
+                'branch you read.',
+            },
+          },
         },
         file: {
           type: 'object',
           description:
             'A bundled file: name, file, path, content — plus `unmerged` and `branch` when it came off ' +
-            'a branch that changed the skill (the note stays beside the content, never inside it).',
+            'a branch that changed the skill (the note stays beside the content, never inside it) — and ' +
+            '`canWrite` for that file on the default branch.',
+          properties: {
+            canWrite: {
+              type: 'boolean',
+              description:
+                'Whether you may commit a change to this file directly on the default branch, under that ' +
+                'branch\'s access rules — the same answer whichever branch you read.',
+            },
+          },
         },
         warnings: {
           type: 'array',