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

package/src/modules/auth/index.ts

@@ -0,0 +1,29 @@
+/**
+ * The entry other modules reach auth through: its admission contract, and
+ * the two things a module checking a credential or refusing a switched-off
+ * account needs to agree with auth on. The composition root wires the rest.
+ *
+ * The embed reaches auth here. Modules written before this entry existed
+ * still import auth's files directly (`auth.service.ts`, the middleware's
+ * request augmentation, `account-admission.ts`); each moves here as it is
+ * touched, and what it needs is added here then — this file holds what is
+ * offered, not everything auth has.
+ */
+export {
+  ACCOUNT_DEACTIVATED_MESSAGE,
+  AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
+  admitEveryone,
+  type AccountAdmissionVerdict,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from './account-admission.js';
+// A constant-time comparison for a secret arriving on a request, so a
+// shared-secret check elsewhere cannot leak the secret's length or prefix by
+// timing — one implementation, auth's.
+export { timingSafeStringEqual } from './password-hash.js';
+// The Express `Request` augmentation (`req.userId`, …): a module whose routes
+// read it imports this entry, never the middleware file.
+import './auth.middleware.js';

package/src/modules/diff/__tests__/diff.service.seed-atomicity.test.ts

@@ -8,6 +8,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { DiffService } from '../diff.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 /**
  * Atomic-seed regression suite.
@@ -53,7 +54,7 @@ async function setup(): Promise<Fixture> {
   const workspaceDir = path.join(workspacesRoot, workspaceId);
   const repoDir = path.join(workspaceDir, 'knowledge-base');
   await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(
+  const workspaceService = newWorkspaceService(
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     testKbContext(),

package/src/modules/diff/__tests__/diff.service.test.ts

@@ -8,6 +8,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { DiffService } from '../diff.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 async function mkTmpRoot(prefix: string): Promise<string> {
   return fs.mkdtemp(path.join(os.tmpdir(), prefix));
@@ -39,7 +40,7 @@ async function setup(): Promise<Fixture> {
   const repoDir = path.join(workspaceDir, 'knowledge-base');
   // Inner `.git` dir is the marker `resolveWorkspaceDir` looks for.
   await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(
+  const workspaceService = newWorkspaceService(
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     testKbContext(),

package/src/modules/diff/__tests__/diff.service.worktree.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { DiffService } from '../diff.service.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
+
+/**
+ * The review session names the branch the workspace is on, read from HEAD
+ * without spawning git. In a worktree `.git` is a FILE naming the worktree's
+ * folder in the repository, where its HEAD lives.
+ */
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-diff-worktree-'));
+});
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+describe('DiffService on a worktree', () => {
+  it("names the worktree's own branch in the review session", async () => {
+    const upstream = path.join(root, 'upstream.git');
+    await git(root, ['init', '--bare', '-b', 'main', upstream]);
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await git(seed, ['init', '-b', 'alice/draft']);
+    await fs.writeFile(path.join(seed, 'page.md'), 'before\n');
+    await git(seed, ['add', '-A']);
+    await git(seed, ['commit', '-m', 'init']);
+    await git(seed, ['push', '-q', upstream, 'alice/draft']);
+
+    const workspacesRoot = path.join(root, 'workspaces');
+    const workspaces = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
+    const diff = new DiffService(
+      workspaces,
+      new WorkspaceMutex(),
+      workspacesRoot,
+      path.join(root, 'backups'),
+      'knowledge-base',
+      new NodeFs(),
+    );
+    workspaces.setDiffService(diff);
+    const workspaceId = workspaceIdForBranch('alice/draft');
+    const info = await workspaces.getOrCreateForBranch('alice/draft');
+    expect((await fs.stat(path.join(info.absolutePath, 'knowledge-base', '.git'))).isFile()).toBe(true);
+
+    // The first look seeds the ledger; a change made after it is pending.
+    expect(await diff.currentSession(workspaceId)).toBeNull();
+    await fs.writeFile(path.join(info.absolutePath, 'knowledge-base', 'page.md'), 'after\n');
+
+    const session = await diff.currentSession(workspaceId);
+    expect(session?.branchName).toBe('alice/draft');
+  });
+});

package/src/modules/diff/diff.service.ts

@@ -4,6 +4,7 @@ import type { FileDiffPayload, PendingChange, ReviewSession, ChangeKind } from '
 import type { IDiffService } from './diff.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkspaceMutex } from '../kb-fs/mutex.js';
+import { gitDirOf } from '../kb-fs/index.js';
 import { isAbsence, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
 import { isDiffable } from './diff.config.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
@@ -385,10 +386,11 @@ export class DiffService implements IDiffService {
   private async tryReadCurrentBranch(workspaceId: string): Promise<string> {
     const workspaceDir = await this.workspaceService.getWorkspacePath(workspaceId);
     try {
-      const head = await fs.readFile(
-        path.join(workspaceDir, this.kbDirName, '.git', 'HEAD'),
-        'utf-8',
-      );
+      // A worktree's `.git` is a FILE naming its folder in the repository,
+      // where its HEAD lives; a full clone's is the folder itself.
+      const gitDir = await gitDirOf(path.join(workspaceDir, this.kbDirName));
+      if (gitDir === null) return '';
+      const head = await fs.readFile(path.join(gitDir, 'HEAD'), 'utf-8');
       const m = head.match(/^ref:\s+refs\/heads\/(.+?)\s*$/);
       return m ? m[1] : '';
     } catch {

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

@@ -168,15 +168,51 @@ describe('EmbedService: minting', () => {
   /**
    * The token rides in the tool result and so in the chat transcript;
    * whoever holds it acts on that one file as its user until it expires.
-   * One hour (Razvan, 2026-10-09), down from the two the embed used before.
+   * Five minutes (Razvan, 2026-10-09): the chat view renews it through its
+   * host when a call is refused, so a short life costs the reader nothing.
    */
-  it('mints a token that lives one hour', async () => {
+  it('mints an open_page token that lives five minutes', async () => {
     const { service } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
+    expect(exp - iat).toBe(5 * 60);
+  });
+
+  /** The connector frames `/embed` and has no host to renew through: its hour stands. */
+  it('mints a connector token that keeps its one-hour lifetime', async () => {
+    const { service } = build();
+    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { iat, exp } = claimsOf(token) as { iat: number; exp: number };
     expect(exp - iat).toBe(60 * 60);
   });
 
+  /**
+   * Both kinds are read by the same verification: each loads while it lives
+   * and is refused as a token once it has run out — the user's after five
+   * minutes, the connector's only after the hour.
+   */
+  it('reads both kinds while they live and refuses each once its own lifetime is over', async () => {
+    vi.useFakeTimers({ toFake: ['Date'] });
+    try {
+      vi.setSystemTime(new Date('2026-10-09T10:00:00Z'));
+      const { service } = build();
+      const user = await service.mintForUser({ userId: USER.id, reference: REPO });
+      const connector = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:04:50Z'));
+      await expect(service.loadFile(user.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T10:05:01Z'));
+      await expect(service.loadFile(user.token)).rejects.toThrow(EmbedTokenError);
+      await expect(service.loadFile(connector.token)).resolves.toMatchObject({ repoRelative: REPO });
+
+      vi.setSystemTime(new Date('2026-10-09T11:00:01Z'));
+      await expect(service.loadFile(connector.token)).rejects.toThrow(EmbedTokenError);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('mints for an outside account — the connector path, unchanged', async () => {
     const { service } = build();
     const { token } = await service.mintToken({
@@ -189,7 +225,9 @@ describe('EmbedService: minting', () => {
 
   it('keeps the token PSEUDONYMOUS — no address, no name', async () => {
     const { service } = build();
-    const { token } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    const { token, embedUrl } = await service.mintToken({ accountId: 'acc-1', email: USER.email, reference: REPO });
+    // The connector's host sizes its frame to the content: its view is told so.
+    expect(embedUrl).toBe(`https://hexis.example/embed?token=${encodeURIComponent(token)}&sizing=content`);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.email);
     expect(JSON.stringify(claimsOf(token))).not.toContain(USER.name);
   });
@@ -711,6 +749,41 @@ describe('EmbedService: a switched-off account', () => {
   });
 });
 
+/**
+ * A distribution's own token-authed route beside the embed (a graph for a
+ * dashboard) asks who is looking before it serves anything, and must judge
+ * the viewer exactly as the embed does.
+ */
+describe('EmbedService: who is looking through a token', () => {
+  it('answers the linked user, their verdicts on the file, and the file', async () => {
+    const { service } = build({ canWrite: false });
+    const { token } = await service.mintForUser({ userId: USER.id, reference: `${REPO}#intro` });
+    expect(await service.viewerOf(token)).toEqual({
+      linked: true,
+      user: expect.objectContaining({ id: USER.id, email: USER.email }),
+      canRead: true,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+  });
+
+  it('answers nobody for an unlinked outside account, and refuses a switched-off one as the embed does', async () => {
+    const unlinked = build({ linkedUserId: null });
+    const outside = await unlinked.service.mintToken({ accountId: 'acc-1', reference: REPO });
+    expect(await unlinked.service.viewerOf(outside.token)).toEqual({
+      linked: false,
+      user: null,
+      canRead: false,
+      canWrite: false,
+      repoRelative: REPO,
+    });
+    const off = build({ active: false });
+    const { token } = await off.service.mintForUser({ userId: USER.id, reference: REPO });
+    await expect(off.service.viewerOf(token)).rejects.toThrow(ACCOUNT_DEACTIVATED_MESSAGE);
+    await expect(off.service.viewerOf('not-a-token')).rejects.toThrow(EmbedTokenError);
+  });
+});
+
 describe('EmbedService: the roles.yaml write gate', () => {
   const ROLES = `${KB}/roles.yaml`;
   const VALID = 'roles:\n  Admin:\n    - a@x.eu\n';

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

@@ -2,6 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import { checkFor } from '@bevel-software/platform-mcp-core';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
@@ -122,6 +123,21 @@ describe('open_page: the listing', () => {
     expect(internal).not.toContain(OPEN_PAGE_TOOL);
   });
 
+  /**
+   * The chat view renews its token by having its host call this tool with
+   * `{ body: { path, heading } }` (see `mcp-app/page.html`). The listing's
+   * own check decides what `/api/mcp` accepts: that shape passes it, and the
+   * flat one the view once sent is refused, so no token ever came back.
+   */
+  it("accepts the chat view's renewal arguments under body, and refuses them flat", async () => {
+    const { registry } = await serve();
+    const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
+    const compiled = checkFor(def.inputs);
+    if (!compiled.checkable) throw new Error(`open_page's schema is not checkable: ${compiled.reason}`);
+    expect(compiled.check({ body: { path: 'Data/Thing.md', heading: 'what-it-is' } })).toEqual([]);
+    expect(compiled.check({ path: 'Data/Thing.md', heading: 'what-it-is' })).not.toEqual([]);
+  });
+
   it('takes a path and an optional heading, and no branch at all', async () => {
     const { registry } = await serve();
     const def = (await registry.listExternal()).find((t) => t.name === OPEN_PAGE_TOOL)!;
@@ -197,6 +213,19 @@ describe('open_page: the answer', () => {
     expect(body.appUrl).toContain('#what-it-is');
   });
 
+  /**
+   * The view renews its token by calling this tool again with the arguments
+   * it was opened with, and the result is all it is told — so the heading
+   * comes back beside the path, and is absent when none was named.
+   */
+  it('echoes the heading beside the path, for the view to call again with', async () => {
+    const { call } = await serve();
+    const { body } = await call({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    expect(body).toMatchObject({ path: 'Data/Thing.md', heading: 'what-it-is' });
+    const plain = await call({ path: 'Data/Thing.md' });
+    expect(plain.body).not.toHaveProperty('heading');
+  });
+
   it('accepts a path with or without the knowledge-base prefix, as read_file documents', async () => {
     const { call, mints } = await serve();
     await call({ path: 'Data/Thing.md' });

package/src/modules/embed/embed.interface.ts

@@ -103,6 +103,19 @@ export interface EmbedLinkedAccount {
  */
 export type EmbedNodeIdResolver = (nodeId: string) => Promise<string | null>;
 
+/** The viewer behind a token, as {@link IEmbedService.viewerOf} answers it. */
+export interface EmbedViewer {
+  /** Whether the token's identity resolved to a user at all. */
+  linked: boolean;
+  /** The linked user; null when unlinked. */
+  user: AuthUser | null;
+  /** Read access on the token's file — always false when unlinked. */
+  canRead: boolean;
+  canWrite: boolean;
+  /** The token's file, repository-relative. */
+  repoRelative: string;
+}
+
 /**
  * What the embed service needs of the workspace: the clone of a branch, and
  * four verbs on one file of it. A port rather than the workspace service
@@ -165,6 +178,17 @@ export interface IEmbedService {
   /** Load the file the token is scoped to, with the viewer's read/write status. */
   loadFile(token: string): Promise<EmbedFileView>;
 
+  /**
+   * Who is looking through `token`, and at what: the resolved viewer (the
+   * linked user, or none), their read and write verdicts on the token's
+   * file, and the file. The one answer a distribution's own token-authed
+   * route beside this surface (a graph for a dashboard, say) asks before it
+   * serves anything, so it judges the viewer exactly as the embed does — the
+   * same token check, the same account link, the same switched-off refusal.
+   * Throws as `loadFile` throws for a token that is invalid or expired.
+   */
+  viewerOf(token: string): Promise<EmbedViewer>;
+
   /**
    * The raw bytes of the embedded file, or of one asset `path` beside it (an
    * image a markdown page shows — a file no reader edits as text, or an SVG,

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/__tests__/git-dir.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { gitDirOf, readGitfile } from '../git-dir.js';
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, ...args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf-8' });
+  return stdout.trim();
+}
+
+/**
+ * The one resolver of a checkout's git directory, checked against what git
+ * itself answers (`rev-parse --absolute-git-dir`) for a clone and a worktree.
+ */
+describe('gitDirOf', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'git-dir-')));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('is the .git folder of a clone and the folder a worktree .git file names, as git says', async () => {
+    const clone = path.join(root, 'clone');
+    await fs.mkdir(clone);
+    await git(clone, 'init', '-q');
+    await git(clone, '-c', 'user.name=T', '-c', 'user.email=t@x.com', 'commit', '-q', '--allow-empty', '-m', 'c');
+    const worktree = path.join(root, 'wt');
+    await git(clone, 'worktree', 'add', '-q', '-b', 'side', worktree);
+
+    for (const dir of [clone, worktree]) {
+      const fromGit = path.resolve(await git(dir, 'rev-parse', '--absolute-git-dir'));
+      expect(path.resolve((await gitDirOf(dir))!)).toBe(await fs.realpath(fromGit));
+    }
+  });
+
+  it('is null with no .git, and with a .git file that names no folder', async () => {
+    expect(await gitDirOf(root)).toBeNull();
+    await fs.writeFile(path.join(root, '.git'), 'not a gitfile\n');
+    expect(await gitDirOf(root)).toBeNull();
+  });
+
+  it('reads exactly what git reads: `gitdir: ` and a path, nothing before, after or around it', async () => {
+    const gitfile = path.join(root, '.git');
+    for (const text of [
+      'not a gitfile\ngitdir: ../elsewhere/wt\n', // a gitdir line further down
+      'gitdir: ../elsewhere/wt\njunk\n', // a second line after the path
+      'gitdir:../elsewhere/wt\n', // no space after the colon
+      'gitdir:  ../elsewhere/wt\n', // a path that starts with a space, which exists nowhere
+      '\ngitdir: ../elsewhere/wt\n', // a blank first line
+    ]) {
+      await fs.writeFile(gitfile, text);
+      const named = await readGitfile(gitfile);
+      // Git refuses each as a gitfile; what this reads of it names no folder
+      // git would open.
+      await expect(git(root, 'rev-parse', '--absolute-git-dir')).rejects.toThrow();
+      expect(named === null || named !== path.resolve(root, '../elsewhere/wt'), JSON.stringify(text)).toBe(true);
+    }
+    await fs.writeFile(gitfile, 'gitdir: ../elsewhere/wt\r\n');
+    expect(await readGitfile(gitfile)).toBe(path.resolve(root, '../elsewhere/wt'));
+  });
+
+  it('resolves a relative gitdir against the file’s own folder', async () => {
+    await fs.writeFile(path.join(root, '.git'), 'gitdir: ../elsewhere/wt\n');
+    expect(await readGitfile(path.join(root, '.git'))).toBe(path.resolve(root, '../elsewhere/wt'));
+    expect(await gitDirOf(root)).toBe(path.resolve(root, '../elsewhere/wt'));
+  });
+});