@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/settings/deployment-settings.service.ts

@@ -1,4 +1,4 @@
-import { eq, inArray } from 'drizzle-orm';
+import { and, eq, inArray } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('settings');
@@ -109,6 +109,16 @@ export const validateHttpsRemote = (value: string): string | null => {
 /**
  * The core catalogue. Order is the order the setup screen renders them in.
  */
+/**
+ * What the `retireMergedBranches` value in effect means: on, unless it says
+ * off. The page saves only `true` or `false`; the environment variable is
+ * typed by a person, so `0`, `off` and `no` (any case) mean off too, and
+ * anything else — unset included — leaves the cleanup on.
+ */
+export function retireMergedBranchesOn(raw: string): boolean {
+  return !/^(false|0|off|no)$/i.test(raw.trim());
+}
+
 export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
@@ -289,6 +299,23 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  {
+    /**
+     * Whether the server removes, on its own, the branches merged change
+     * requests left behind (`WorkflowService.retireLeftoverMergedBranches`).
+     * On unless set to `false`; a blanked field puts the default back. Read
+     * at every round, so it applies without a restart. It covers that cleanup
+     * only: the removal of a branch when its change request is merged does
+     * not ask it.
+     */
+    key: 'retireMergedBranches',
+    envVar: 'RETIRE_MERGED_BRANCHES',
+    section: 'knowledge-base',
+    blankMeansDefault: true,
+    unsetMeans: 'true',
+    validate: (v) => (v === 'true' || v === 'false' ? null : 'Either true or false.'),
+  },
+
   {
     /**
      * The credential a git host's webhook or a pipeline presents to
@@ -372,6 +399,35 @@ export const CORE_SETTINGS: SettingDef[] = [
     validate: (v) =>
       parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
   },
+
+  {
+    /**
+     * Which starter pack the first admin chose for a new knowledge base — a
+     * pack's id, or `none` for "I'll start from scratch" — written once, by
+     * the deployment, when the choice landed (see
+     * `modules/onboarding/starter-pack.service.ts`). Its presence is what
+     * retires the "What does your team do?" card for good; its value is what
+     * the first-page prompt and the agent's first-run note follow. Internal:
+     * a fact about what happened, not something the setup screen offers.
+     */
+    key: 'starterPack',
+    section: 'knowledge-base',
+    internal: true,
+    validate: (v) => (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v) ? null : 'A starter pack id is lowercase letters, digits and hyphens.'),
+  },
+  {
+    /**
+     * The claim an admin holds while their starter-pack choice is being
+     * written: `<user id> <epoch ms>`, inserted only if absent so two replicas
+     * cannot both write, and released once the choice is recorded. A claim
+     * nobody released in time is a process that died mid-write and is taken
+     * over (see `starter-pack.service.ts`). Internal, like the choice.
+     */
+    key: 'starterPackClaim',
+    section: 'knowledge-base',
+    internal: true,
+    validate: (v) => (/^\S+ \d+$/.test(v) ? null : 'A claim is a user id and a time.'),
+  },
 ];
 
 /**
@@ -724,6 +780,61 @@ export class DeploymentSettingsService {
     await this.save(entries, updatedBy, 'deployment');
   }
 
+  /**
+   * {@link record} one value ONLY IF NOTHING IS THERE, and say whether it was
+   * this call that put it there. The row is the claim for a flow that must
+   * happen once across every replica (the starter-pack choice): the insert
+   * yields to a row already there, so of two replicas claiming at once the
+   * database lets exactly one through. Validated as `record` is; a blank
+   * value is no claim (it would be a clear) and answers false.
+   */
+  async recordIfAbsent(key: string, value: string, updatedBy: string | null): Promise<boolean> {
+    const write = this.plan({ [key]: value }, 'deployment').toWrite.find((w) => w.key === key);
+    if (!write) return false;
+    const encrypted = write.def.secret === true;
+    const stored = encrypted ? this.crypto!.encrypt(write.value) : write.value;
+    const inserted = await this.db
+      .insert(deploymentSettings)
+      .values({ key, value: stored, encrypted, updatedBy })
+      .onConflictDoNothing({ target: deploymentSettings.key })
+      .returning({ key: deploymentSettings.key });
+    if (inserted.length === 0) return false;
+    this.stored.set(key, write.value);
+    return true;
+  }
+
+  /**
+   * Replace a plain setting's value ONLY IF it still reads `expected` —
+   * with `next`, or with nothing when `next` is null — and say whether it
+   * was this call that did it. One statement, so of two replicas acting on
+   * what they both read, the database lets exactly one through: the other
+   * finds the value gone or changed and answers false. For the claim flows
+   * that {@link recordIfAbsent} opens: taking over a claim that expired, and
+   * releasing one's own without touching a successor's. Plain settings only;
+   * `next` is validated as {@link record} would.
+   */
+  async swapIfValue(key: string, expected: string, next: string | null, updatedBy: string | null): Promise<boolean> {
+    const def = this.defs.get(key);
+    if (!def || def.secret) return false;
+    const same = and(eq(deploymentSettings.key, key), eq(deploymentSettings.value, expected));
+    if (next === null) {
+      const gone = await this.db.delete(deploymentSettings).where(same).returning({ key: deploymentSettings.key });
+      if (gone.length === 0) return false;
+      this.stored.delete(key);
+      return true;
+    }
+    const write = this.plan({ [key]: next }, 'deployment').toWrite.find((w) => w.key === key);
+    if (!write) return false;
+    const swapped = await this.db
+      .update(deploymentSettings)
+      .set({ value: write.value, updatedBy, updatedAt: new Date() })
+      .where(same)
+      .returning({ key: deploymentSettings.key });
+    if (swapped.length === 0) return false;
+    this.stored.set(key, write.value);
+    return true;
+  }
+
   /** Validate a batch and return the writes (and the clears) it amounts to; throws on any problem. */
   private plan(
     entries: Record<string, string>,
@@ -952,6 +1063,25 @@ export class DeploymentSettingsService {
     return `${OIDC_VERIFICATION_PREFIX}${fingerprint}`;
   }
 
+  /**
+   * One plain (never sealed) setting as the DATABASE has it now, taken into
+   * this replica's cache on the way: for the rare setting a running
+   * deployment writes, so a replica that did not serve the write still
+   * answers with it. The environment still wins, as in {@link resolve}.
+   */
+  async reload(key: string): Promise<string> {
+    const def = this.defs.get(key);
+    if (!def || def.secret) return this.resolve(key);
+    const rows = await this.db
+      .select({ value: deploymentSettings.value, encrypted: deploymentSettings.encrypted })
+      .from(deploymentSettings)
+      .where(eq(deploymentSettings.key, key));
+    const row = rows.find((r) => !r.encrypted);
+    if (row) this.stored.set(key, row.value);
+    else this.stored.delete(key);
+    return this.resolve(key);
+  }
+
   /** Remove one stored row (used by tests and by `prune`). */
   async clear(key: string): Promise<void> {
     await this.db.delete(deploymentSettings).where(eq(deploymentSettings.key, key));

package/src/modules/settings/repository-source.ts

@@ -34,7 +34,7 @@ export interface GitHubAppRepository {
    * Make sure {@link token} answers with one that is still good. `asked`
    * is for a caller waiting on the answer itself, who is told a failure.
    */
-  prepare(opts?: { asked?: boolean }): Promise<void>;
+  prepare(opts?: { asked?: boolean; refused?: boolean }): Promise<void>;
   /** Whether the deployment may be pointed at this repository (`owner/name`). */
   permits(repository: string, read: SettingReader): boolean;
   /** Whether the app, its installation and a repository are all there. */
@@ -98,7 +98,7 @@ export class RepositorySource {
     this.credentials = {
       username: () => this.username(),
       token: () => this.token(),
-      prepare: () => this.prepare(),
+      prepare: (opts) => this.prepare(opts),
     };
   }
 
@@ -185,8 +185,8 @@ export class RepositorySource {
     }
   }
 
-  private async prepare(): Promise<void> {
-    if (this.inEffect === 'github-app') await this.opts.githubApp?.prepare();
+  private async prepare(opts?: { refused?: boolean }): Promise<void> {
+    if (this.inEffect === 'github-app') await this.opts.githubApp?.prepare(opts);
   }
 
   private tokenIn(read: SettingReader): string {

package/src/modules/skills/__tests__/skills.tools.description.test.ts

@@ -1,3 +1,4 @@
+import { callLine } from '@bevel-software/platform-mcp-core';
 import express from 'express';
 import { describe, expect, it } from 'vitest';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
@@ -46,7 +47,10 @@ describe('the skill tools name the available skills within the description cap',
     // than guessed, so the names below are sized to fill it EXACTLY.
     const probe = await served([skill('x')]);
     const fixed = probe.list.description!.slice(GUIDE_FIRST_SENTENCE.length + 1, probe.list.description!.indexOf('Currently available skills: '));
-    const budget = TOOL_DESCRIPTION_CAP - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
+    // And the `Call:` line a client is handed ahead of all of it, with the
+    // blank line after it: the example counts toward the cap too.
+    const call = callLine(`KNOWLEDGE_BASE.list_skills`, probe.list.inputs).length + 2;
+    const budget = TOOL_DESCRIPTION_CAP - call - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
     const head = 'Currently available skills: '.length;
     // Twenty-one names, the LAST one short — shorter than the ", and 1 more…"
     // tail a cut before it would carry — and the first one sized so the

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

@@ -1,11 +1,14 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { callLine } from '@bevel-software/platform-mcp-core';
+import type { IToolRegistry, JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
 import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
 import { GUIDE_FIRST_SENTENCE } from '../tool-registry/guide-first.js';
 import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
+import { bodyEnvelope, declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
 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';
 
 /**
@@ -22,6 +25,39 @@ const BRANCH_SKILLS_INPUT = {
     'a branch that does not exist answers 404 naming it. Omit it for the approved skills.',
 };
 
+/** What `list_skills` takes. A const so the route's check and the def share one declaration. */
+const LIST_SKILLS_INPUTS = {
+  type: 'object' as const,
+  properties: { branch: BRANCH_SKILLS_INPUT },
+  additionalProperties: false,
+};
+
+/** What `get_skill` takes. A const for the same reason as {@link LIST_SKILLS_INPUTS}. */
+const GET_SKILL_INPUTS = {
+  type: 'object' as const,
+  properties: {
+    name: { type: 'string' as const, minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+    file: {
+      type: 'string' as const,
+      description:
+        'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
+        'fetch its content instead of the body.',
+    },
+    version: {
+      type: 'string' as const,
+      description:
+        'Optional: the declared version to load (e.g. `1.4.0` — the `version` that `list_skills` ' +
+        'reports: `metadata.version`, else `version`, else `lifecycle.version`). Omitted, the skill is loaded as it ' +
+        'is now, which is the latest. Given, the skill — or the `file` — is served as it was at the most ' +
+        'recent commit that declared that version; a version the skill never declared answers ' +
+        '`version_not_found` with the versions it did declare.',
+    },
+    branch: BRANCH_SKILLS_INPUT,
+  },
+  required: ['name'],
+  additionalProperties: false,
+};
+
 /**
  * Registers the two skill tools (both surfaces) and hosts their endpoints.
  *
@@ -51,6 +87,11 @@ export function registerSkillsTools(
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+  // Both defs are built per catalog listing (their descriptions name the skills
+  // THIS caller may read), so declare the arguments here as well: a direct REST
+  // call that lands before the first listing must be checked against them too.
+  declareRouteTool('list_skills', LIST_SKILLS_INPUTS);
+  declareRouteTool('get_skill', GET_SKILL_INPUTS);
 
   router.post(
     '/agent/tools/list_skills',
@@ -139,9 +180,15 @@ async function availableSkillsLine(skillService: ISkillService, userEmail: strin
   return `${head}${names.slice(0, shown).join(', ')}${rest(shown)}`;
 }
 
-/** What the fixed part of a description leaves the skills line, with the guide-first sentence counted. */
-function skillsLineBudget(fixed: string): number {
-  return TOOL_DESCRIPTION_CAP - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
+/**
+ * What the fixed part of a description leaves the skills line, with the
+ * `Call:` line ahead of everything (and the blank line after it) and the
+ * guide-first sentence counted. The call line is generated from the schema
+ * the tool advertises: its flat `inputs` inside the `body` envelope.
+ */
+function skillsLineBudget(name: string, inputs: JsonSchema, fixed: string): number {
+  const call = callLine(`${EXTERNAL_KB_MANUAL_NAME}.${name}`, bodyEnvelope(inputs)).length + 2;
+  return TOOL_DESCRIPTION_CAP - call - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
 }
 
 const LIST_SKILLS_DESCRIPTION =
@@ -158,13 +205,9 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
     name: 'list_skills',
     description:
       LIST_SKILLS_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget(LIST_SKILLS_DESCRIPTION))),
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION))),
     path: '/api/agent/tools/list_skills',
-    inputs: {
-      type: 'object',
-      properties: { branch: BRANCH_SKILLS_INPUT },
-      additionalProperties: false,
-    },
+    inputs: LIST_SKILLS_INPUTS,
     outputs: {
       type: 'object',
       properties: {
@@ -210,32 +253,9 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
     name: 'get_skill',
     description:
       GET_SKILL_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget(GET_SKILL_DESCRIPTION))),
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION))),
     path: '/api/agent/tools/get_skill',
-    inputs: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
-        file: {
-          type: 'string',
-          description:
-            'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
-            'fetch its content instead of the body.',
-        },
-        version: {
-          type: 'string',
-          description:
-            'Optional: the declared version to load (e.g. `1.4.0` — the `version` that `list_skills` ' +
-            'reports: `metadata.version`, else `version`, else `lifecycle.version`). Omitted, the skill is loaded as it ' +
-            'is now, which is the latest. Given, the skill — or the `file` — is served as it was at the most ' +
-            'recent commit that declared that version; a version the skill never declared answers ' +
-            '`version_not_found` with the versions it did declare.',
-        },
-        branch: BRANCH_SKILLS_INPUT,
-      },
-      required: ['name'],
-      additionalProperties: false,
-    },
+    inputs: GET_SKILL_INPUTS,
     outputs: {
       type: 'object',
       description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',

package/src/modules/tool-auth/__tests__/connection-key-rejection.test.ts

@@ -11,6 +11,7 @@ import type { AuthService } from '../../auth/auth.service.js';
 import { InternalTokenService } from '../internal-token.service.js';
 import { createManualAuthMiddleware, createToolAuthMiddleware } from '../tool-auth.middleware.js';
 import type { IExternalApiKeyService } from '../external-api-key.interface.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/account-admission.js';
 
 /**
  * A bearer shaped like a connection key that does not verify is answered with
@@ -24,6 +25,8 @@ import type { IExternalApiKeyService } from '../external-api-key.interface.js';
  * server requests, with the same gate `create-core-server.ts` puts on each.
  */
 const BAD_KEY = 'bevel_revokedKeyThatMustNeverBeEchoed';
+/** A second refused key: on the switched-off service it is not one of a switched-off account. */
+const OTHER_BAD_KEY = 'bevel_unknownKeyThatMustNeverBeEchoed';
 const RESOURCE_METADATA_URL = 'https://hexis.example/.well-known/oauth-protected-resource/api/mcp';
 const DISCOVERY_CHALLENGE = `Bearer realm="bevel-mcp", resource_metadata="${RESOURCE_METADATA_URL}"`;
 const KEY_CHALLENGE = 'Bearer error="invalid_token", error_description="Invalid or revoked connection key"';
@@ -190,3 +193,32 @@ describe('the REST agent surface keeps its challenge for everything but a key',
     }
   });
 });
+
+describe('a live connection key whose account is switched off is told so', () => {
+  const switchedOffKeys = {
+    ...externalApiKeys,
+    isKeyOfSwitchedOffAccount: async (t: string) => t === BAD_KEY,
+  } as unknown as IExternalApiKeyService;
+
+  for (const endpoint of KEY_ENDPOINTS) {
+    it(`${endpoint.name}: 401 with the switched-off reason, not an invitation to mint a new key`, async () => {
+      const base = await start(switchedOffKeys);
+      const res = await call(base, endpoint.method, endpoint.path, BAD_KEY);
+      expect(res.status).toBe(401);
+      expect(res.headers.get('www-authenticate')).toBe(
+        'Bearer error="invalid_token", error_description="The account of this connection key is switched off"',
+      );
+      expect(await res.json()).toEqual({ error: ACCOUNT_DEACTIVATED_MESSAGE });
+      expect(logged.join('\n')).not.toContain(BAD_KEY);
+    });
+
+    it(`${endpoint.name}: any other refused key on the same service is still told it is invalid`, async () => {
+      const base = await start(switchedOffKeys);
+      const res = await call(base, endpoint.method, endpoint.path, OTHER_BAD_KEY);
+      expect(res.status).toBe(401);
+      expect(res.headers.get('www-authenticate')).toBe(KEY_CHALLENGE);
+      expect(await res.json()).toEqual(KEY_BODY);
+      expect(logged.join('\n')).not.toContain(OTHER_BAD_KEY);
+    });
+  }
+});

package/src/modules/tool-auth/__tests__/external-api-key.service.test.ts

@@ -276,6 +276,71 @@ describe('ExternalApiKeyService', () => {
       expect(warn).toHaveBeenCalled();
       warn.mockRestore();
     });
+
+    /**
+     * A key's FIRST use is an agent arriving — what the onboarding waits for
+     * — so the owner is told once the stamp has landed, and once only. The
+     * first stamp is a CLAIM (`… where last_used_at is null … returning`):
+     * the request the database hands the row to announces, a racing one
+     * loses the claim, stamps the ordinary way and says nothing, and a key
+     * stamped before is touched without a word.
+     */
+    it("announces a key's first use to its owner once the claim has landed, and never otherwise", async () => {
+      const row = { tokenId: 'tok-1', label: 'Laptop', lastUsedAt: null, userId: 'user-7', email: 'a@x.io', name: 'Alice', avatarUrl: null };
+      const events = { emit: vi.fn() };
+      // The claim's answer is held back, to pin that the announcement waits for it.
+      let claimed!: (rows: { id: string }[]) => void;
+      const claim = new Promise<{ id: string }[]>((resolve) => (claimed = resolve));
+      const first = makeFakeDb([[row], claim]);
+      await new ExternalApiKeyService(first.db, 'bevel_', {}, events).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(first.calls.update).toHaveLength(1);
+      expect(first.calls.set[0][0]).toHaveProperty('lastUsedAt');
+      expect(renderSql(first.calls.where[1][0]).sql).toMatch(/"api_tokens"."id" = \$1 and "api_tokens"."last_used_at" is null/);
+      expect(events.emit).not.toHaveBeenCalled();
+      claimed([{ id: 'tok-1' }]);
+      await flushMicrotasks();
+      expect(events.emit).toHaveBeenCalledTimes(1);
+      expect(events.emit).toHaveBeenCalledWith({
+        kind: 'agent-connected',
+        forUserId: 'user-7',
+        client: 'Laptop',
+        agentKind: 'key',
+        at: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+      });
+
+      // A racing request lost the claim: the ordinary stamp, and no announcement.
+      const lost = makeFakeDb([[row], [], undefined]);
+      const lostEvents = { emit: vi.fn() };
+      await new ExternalApiKeyService(lost.db, 'bevel_', {}, lostEvents).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(lost.calls.update).toHaveLength(2);
+      expect(lostEvents.emit).not.toHaveBeenCalled();
+
+      // A key stamped before: touched, and nobody is told.
+      const again = makeFakeDb([[{ ...row, lastUsedAt: new Date('2026-10-07T12:00:00Z') }], undefined]);
+      const laterEvents = { emit: vi.fn() };
+      await new ExternalApiKeyService(again.db, 'bevel_', {}, laterEvents).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(again.calls.update).toHaveLength(1);
+      expect(laterEvents.emit).not.toHaveBeenCalled();
+    });
+
+    it('announces nothing when the first stamp could not be written', async () => {
+      const row = { tokenId: 'tok-1', label: 'Laptop', lastUsedAt: null, userId: 'user-7', email: 'a@x.io', name: 'Alice', avatarUrl: null };
+      let fail!: (err: Error) => void;
+      const claim = new Promise<{ id: string }[]>((_resolve, reject) => (fail = reject));
+      const { db } = makeFakeDb([[row], claim]);
+      const events = { emit: vi.fn() };
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const user = await new ExternalApiKeyService(db, 'bevel_', {}, events).verifyAndLoadUser('bevel_abc');
+      expect(user?.id).toBe('user-7');
+      fail(new Error('connection lost'));
+      await flushMicrotasks();
+      expect(events.emit).not.toHaveBeenCalled();
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
   });
 
   describe('listForUser', () => {

package/src/modules/tool-auth/connection-key-rejection.ts

@@ -1,4 +1,5 @@
 import type { Response } from 'express';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/account-admission.js';
 
 /**
  * How every key-authenticated endpoint answers a bearer that LOOKS like a
@@ -19,7 +20,16 @@ export const INVALID_CONNECTION_KEY_CHALLENGE =
 export const INVALID_CONNECTION_KEY_MESSAGE =
   'Invalid or revoked connection key. Mint a new one in External agent access.';
 
-export function rejectConnectionKey(res: Response): void {
-  res.setHeader('WWW-Authenticate', INVALID_CONNECTION_KEY_CHALLENGE);
-  res.status(401).json({ error: INVALID_CONNECTION_KEY_MESSAGE });
+/**
+ * A live key whose account an admin switched off: still a plain
+ * `invalid_token` (no sign-in invitation, see above), but told the real
+ * reason — telling them to mint a new key would send them to something
+ * they cannot do.
+ */
+export const SWITCHED_OFF_CONNECTION_KEY_CHALLENGE =
+  'Bearer error="invalid_token", error_description="The account of this connection key is switched off"';
+
+export function rejectConnectionKey(res: Response, opts: { switchedOff?: boolean } = {}): void {
+  res.setHeader('WWW-Authenticate', opts.switchedOff ? SWITCHED_OFF_CONNECTION_KEY_CHALLENGE : INVALID_CONNECTION_KEY_CHALLENGE);
+  res.status(401).json({ error: opts.switchedOff ? ACCOUNT_DEACTIVATED_MESSAGE : INVALID_CONNECTION_KEY_MESSAGE });
 }

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -140,6 +140,15 @@ export interface IExternalApiKeyService {
     plaintext: string,
   ): Promise<{ tokenId: string; user: AuthUser } | null>;
 
+  /**
+   * For a key {@link verifyAndLoadToken} refused: whether it is a live key
+   * whose account an admin switched off — the one refusal its holder must
+   * not be told to mint a new key over (they cannot; the account is off).
+   * Asked only on the refusal path, so a working key costs nothing more.
+   * Optional: without it every refused key is reported as invalid.
+   */
+  isKeyOfSwitchedOffAccount?(plaintext: string): Promise<boolean>;
+
   /** Active + revoked tokens for the user, newest-first. */
   listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
 

package/src/modules/tool-auth/external-api-key.service.ts

@@ -3,7 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('external-api-key');
 import { and, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
-import type { AuthUser } from '@bevel-software/platform-shared';
+import type { AgentConnectedEvent, AuthUser } from '@bevel-software/platform-shared';
 import type { Database } from '../database/connection.js';
 import { externalApiKeys, users } from '../database/schema.js';
 import {
@@ -51,6 +51,12 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     private readonly db: Database,
     private readonly keyPrefix: string,
     private readonly kinds: Readonly<Record<string, KeyKindSpec>> = {},
+    /**
+     * Where a key's FIRST use is announced to its owner (`agent-connected`,
+     * see `verifyAndLoadToken`). Optional: without it the stamp is written
+     * and nobody is told.
+     */
+    private readonly events?: { emit(event: AgentConnectedEvent): void },
   ) {
     this.prefixes = [keyPrefix, ...Object.values(kinds).map((k) => k.prefix)];
   }
@@ -97,6 +103,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     return resolved ? resolved.user : null;
   }
 
+  async isKeyOfSwitchedOffAccount(plaintext: string): Promise<boolean> {
+    if (!this.looksLikeExternalApiKey(plaintext)) return false;
+    // The same key `verifyAndLoadToken` would accept (known, not revoked),
+    // but on an account that is off.
+    const [row] = await this.db
+      .select({ id: externalApiKeys.id })
+      .from(externalApiKeys)
+      .innerJoin(users, eq(externalApiKeys.userId, users.id))
+      .where(and(eq(externalApiKeys.tokenHash, hashToken(plaintext)), isNull(externalApiKeys.revokedAt), isNotNull(users.deactivatedAt)))
+      .limit(1);
+    return row !== undefined;
+  }
+
   async verifyAndLoadToken(
     plaintext: string,
   ): Promise<{ tokenId: string; user: AuthUser } | null> {
@@ -114,6 +133,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     const [row] = await this.db
       .select({
         tokenId: externalApiKeys.id,
+        label: externalApiKeys.label,
+        lastUsedAt: externalApiKeys.lastUsedAt,
         userId: users.id,
         email: users.email,
         name: users.name,
@@ -130,9 +151,28 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // the UPDATE. A failed touch is logged but never blocks the caller —
     // the worst case is a slightly stale `last_used_at`, which is fine for
     // a "when was this key last used" audit view.
-    this.touchLastUsed(row.tokenId).catch((err) => {
-      log.warn('touchLastUsed failed:', { err });
-    });
+    //
+    // A key's FIRST use is an agent that has just reached the platform —
+    // what the onboarding waits for — so its owner is told once the stamp
+    // has landed. A key never stamped is CLAIMED (`claimFirstUse`), so of
+    // two requests racing its first use exactly one announces it; a key
+    // stamped before is touched and nobody is told.
+    const stamped = row.lastUsedAt === null ? this.claimFirstUse(row.tokenId) : this.touchLastUsed(row.tokenId).then(() => false);
+    stamped.then(
+      (first) => {
+        if (!first) return;
+        this.events?.emit({
+          kind: 'agent-connected',
+          forUserId: row.userId,
+          client: row.label,
+          agentKind: 'key',
+          at: new Date().toISOString(),
+        });
+      },
+      (err) => {
+        log.warn('touchLastUsed failed:', { err });
+      },
+    );
 
     return {
       tokenId: row.tokenId,
@@ -280,6 +320,23 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       .set({ lastUsedAt: new Date() })
       .where(eq(externalApiKeys.id, tokenId));
   }
+
+  /**
+   * The first stamp as ONE statement: the row is taken only while
+   * `last_used_at` is still null, so of two requests (or two replicas)
+   * racing a key's first use the database hands it to exactly one, which
+   * answers true. The loser stamps the ordinary way and answers false.
+   */
+  private async claimFirstUse(tokenId: string): Promise<boolean> {
+    const won = await this.db
+      .update(externalApiKeys)
+      .set({ lastUsedAt: new Date() })
+      .where(and(eq(externalApiKeys.id, tokenId), isNull(externalApiKeys.lastUsedAt)))
+      .returning({ id: externalApiKeys.id });
+    if (won.length > 0) return true;
+    await this.touchLastUsed(tokenId);
+    return false;
+  }
 }
 
 function hashToken(plaintext: string): string {

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -6,7 +6,11 @@ import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
 import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
 import { InternalTokenService } from './internal-token.service.js';
-import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
+import {
+  INVALID_CONNECTION_KEY_CHALLENGE,
+  INVALID_CONNECTION_KEY_MESSAGE,
+  SWITCHED_OFF_CONNECTION_KEY_CHALLENGE,
+} from './connection-key-rejection.js';
 
 /**
  * What the `toolAuth` middleware resolves a bearer to, before the per-call
@@ -165,9 +169,14 @@ export function createTokenVerifier(
     // External API key → external caller. (verifyAndLoadToken may throw → propagates → caller maps to 500.)
     if (externalApiKeyService.looksLikeExternalApiKey(token)) {
       const resolved = await externalApiKeyService.verifyAndLoadToken(token);
-      return resolved
-        ? { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } }
-        : { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
+      if (resolved) {
+        return { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } };
+      }
+      // A live key of a switched-off account is told so, not sent to mint another.
+      if (await externalApiKeyService.isKeyOfSwitchedOffAccount?.(token)) {
+        return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE, challenge: SWITCHED_OFF_CONNECTION_KEY_CHALLENGE };
+      }
+      return { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
     }
 
     return missing;