drafted 1.24.7 → 1.25.0

package/mcp/server.mjs

@@ -15,6 +15,7 @@ import { join, dirname, basename, extname, resolve } from 'path';
 import { homedir, platform, release as osRelease, arch as osArch } from 'os';
 import { detectGwsStatus } from './gws-status.mjs';
 import { fileURLToPath } from 'url';
+import { splitRange } from '../src/shared/commit-range.mjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
 import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
@@ -3359,7 +3360,8 @@ tool('minion', {
   context: z.object({
     frames: z.array(z.string()).describe('frame ids in the SAME project, max 20'),
   }).optional().describe('[create|update] the brief pack the Minion may read and answer from (read_brief). DISCLOSED to every visitor — include only what they may see. The Minion cannot read anything else in the org.'),
-  visitorDailyLimit: z.number().optional().describe('[create|update] turns per visitor per UTC day (default 30); dailyLimit is shared by all visitors'),
+  weeklyLimit: z.number().optional().describe('[create|update] turns per ISO week (UTC, resets Monday) shared by all visitors (default 350); the org also sets it in Settings → Minions, next to measured usage'),
+  visitorWeeklyLimit: z.number().optional().describe('[create|update] turns per visitor per ISO week (default 210)'),
   limit: z.number().optional().describe('[list] max results per page (default 25, max 100)'),
   offset: z.number().optional().describe('[list] skip N results for pagination (default 0)'),
   compact: z.boolean().optional().describe('[list] return only {id,slug,name,enabled,projectId} per Minion'),
@@ -3388,7 +3390,7 @@ tool('minion', {
       }
       case 'create': {
         // projectId lives in the BODY (the POST route reads body, ignores the query).
-        const { name, description, target, checklist, output, enabled, context, visitorDailyLimit } = args;
+        const { name, description, target, checklist, output, enabled, context, weeklyLimit, visitorWeeklyLimit } = args;
         if (!name || !target || !Array.isArray(checklist) || !output) {
           throw new Error('name, target, checklist[], and output are required for action=create');
         }
@@ -3396,14 +3398,15 @@ tool('minion', {
         if (description !== undefined) body.description = description;
         if (enabled !== undefined) body.enabled = enabled;
         if (context !== undefined) body.context = context;
-        if (visitorDailyLimit !== undefined) body.visitorDailyLimit = visitorDailyLimit;
+        if (weeklyLimit !== undefined) body.weeklyLimit = weeklyLimit;
+        if (visitorWeeklyLimit !== undefined) body.visitorWeeklyLimit = visitorWeeklyLimit;
         const created = await scoped(() => api('POST', '/api/minions', body));
         return ok({ ...created, projectPath });
       }
       case 'update': {
         if (!args.id) throw new Error('id is required for action=update');
         const body = {};
-        for (const k of ['name', 'description', 'target', 'checklist', 'output', 'enabled', 'context', 'visitorDailyLimit']) {
+        for (const k of ['name', 'description', 'target', 'checklist', 'output', 'enabled', 'context', 'weeklyLimit', 'visitorWeeklyLimit']) {
           if (args[k] !== undefined) body[k] = args[k];
         }
         if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
@@ -3459,8 +3462,8 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: todo, in_progress, in_review, done, canceled -- the Linear set minus Backlog, which this product deliberately does not have (a Backlog column only ever accumulates). The names this system used to store -- open, scheduled, needs_review, needs_decision, failed, backlog -- are still ACCEPTED and normalised (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (ONE link graph across wiki pages, skills, frames, tasks, projects and urls: `link` relates any wiki page, skill or frame to any other node or to a url; `links` on a wiki page, skill or frame lists its edges plus its backlinks from every kind of node, and on a project path lists the tasks linked to that project. Links written IN content are edges too, parsed on every write — markdown links (relative wiki links, or `/o/<org>/...` addresses from any wiki page, skill or frame), HTML `<a href>` addresses, OKF `related:` frontmatter; a bare address in prose is not a link; `unlink` removes only declared ones, so edit the content to drop a written link. A link is stored by ID, so `mv` never breaks it; a link to a page not written yet is stored by path and connects when the page is written). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, `.skillinstall/` is stripped on skill push. ANCHORED SKILLS are enforced by the server on every content write (frames, wiki pages, skills) in the scope they are anchored to — an org, a folder or a project: a write from a session that has not read them is refused with HTTP 428 `anchor_gate`, and the refusal carries the rule text and the `fs(read)` path of each skill; read them, then retry. Anchored FRAMES are not enforced — they are suggested reading only.\n\nLARGE WRITES (chunked): when the content is too big for ONE tool call — a ~1 MB app-frame .html, or any text write from a remote transport, which has no access to a local file — write it in ordered chunks: fs(write, path=…, chunkIndex=0, chunkTotal=N, content=<slice 0>), then 1, … N-1. Each chunk is a contiguous slice of the final file and every chunk carries the same chunkTotal. NOTHING is written until the final chunk (N-1), which performs the one ordinary write: no half-uploaded frame is ever served, no intermediate version is created, app-frame detection sees the whole document, and expectedUpdatedAt is enforced on that single write. A missing index fails at the final chunk with the missing indexes named; a duplicate index fails loudly; chunk 0 restarts a broken upload. Prefer a handful of large chunks (~64–256 KB each) over hundreds of tiny ones. Reading a big frame back is paged — see the read action chars window and nextChars.', {
-  action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links']).describe('Filesystem verb.'),
+tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: todo, in_progress, in_review, done, canceled -- the Linear set minus Backlog, which this product deliberately does not have (a Backlog column only ever accumulates). The names this system used to store -- open, scheduled, needs_review, needs_decision, failed, backlog -- are still ACCEPTED and normalised (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (ONE link graph across wiki pages, skills, frames, tasks, projects and urls: `link` relates any wiki page, skill or frame to any other node or to a url; `links` on a wiki page, skill or frame lists its edges plus its backlinks from every kind of node, and on a project path lists the tasks linked to that project. Links written IN content are edges too, parsed on every write — markdown links (relative wiki links, or `/o/<org>/...` addresses from any wiki page, skill or frame), HTML `<a href>` addresses, OKF `related:` frontmatter; a bare address in prose is not a link; `unlink` removes only declared ones, so edit the content to drop a written link. A link is stored by ID, so `mv` never breaks it; a link to a page not written yet is stored by path and connects when the page is written). `status` / `log` / `diff` read a frame\'s version history — `status` gives the head commit plus every Minion / wiki page / frame that records being built from it and how far behind it is, `log` lists commits (author, person vs agent, message, how many writes were squashed into each), and `diff` returns a text-level change summary per content type (Excalidraw element labels, markdown/HTML hunks) — never the full content, always capped. `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, `.skillinstall/` is stripped on skill push. ANCHORED SKILLS are enforced by the server on every content write (frames, wiki pages, skills) in the scope they are anchored to — an org, a folder or a project: a write from a session that has not read them is refused with HTTP 428 `anchor_gate`, and the refusal carries the rule text and the `fs(read)` path of each skill; read them, then retry. Anchored FRAMES are not enforced — they are suggested reading only.\n\nLARGE WRITES (chunked): when the content is too big for ONE tool call — a ~1 MB app-frame .html, or any text write from a remote transport, which has no access to a local file — write it in ordered chunks: fs(write, path=…, chunkIndex=0, chunkTotal=N, content=<slice 0>), then 1, … N-1. Each chunk is a contiguous slice of the final file and every chunk carries the same chunkTotal. NOTHING is written until the final chunk (N-1), which performs the one ordinary write: no half-uploaded frame is ever served, no intermediate version is created, app-frame detection sees the whole document, and expectedUpdatedAt is enforced on that single write. A missing index fails at the final chunk with the missing indexes named; a duplicate index fails loudly; chunk 0 restarts a broken upload. Prefer a handful of large chunks (~64–256 KB each) over hundreds of tiny ones. Reading a big frame back is paged — see the read action chars window and nextChars.', {
+  action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links', 'status', 'log', 'diff']).describe('Filesystem verb. `status` / `log` / `diff` read a frame\'s version history (see their descriptions in the tool text).'),
   path: z.string().describe('Drafted path: /o/<org>[/<folder…>]/wiki/... | .../skills/... | .../tasks/... | .../projects/... — a folder chain may precede any root (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
   to: z.string().optional().describe('[mv] destination — a frame path for a frame, a container path (/<layer> or /<layer>/<lane>, optionally prefixed /o/<org>/projects/<other-project>/… to move across projects) for a lane or layer, or the NEW NAME when the source path is a project; [link/unlink] target path — a wiki page (/o/<org>[/<folder>]/wiki/<page>), a skill (/o/<org>/skills/<slug>), a task, a frame path, or a project path (/o/<org>/projects/<project>) to link a task to a project'),
   url: z.string().optional().describe('[link/unlink] external target URL, instead of `to` (a link is internal-by-id OR external-by-url, never both)'),
@@ -3479,6 +3482,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
   readme: z.string().optional().describe('[write] README.md markdown for a skill at /o/<org>/skills/<slug> — optional on both create and update. Stored as a supporting skill file so the skill directory renders a landing page on GitHub when exported; a skill created without one is returned with a warning, never rejected. Equivalent to a later fs(write, path="/o/<org>/skills/<slug>/README.md").'),
   position: z.number().int().min(0).optional().describe('[mv] on a LAYER path, no `to`: move the layer to this 0-based index in the project\'s layer order (0 = first; `ls` of the project shows the order). A layer born from a first write is appended last, so use this to pin one first.'),
   recursive: z.boolean().optional().describe('[ls] recurse into subdirectories'),
+  range: z.string().optional().describe('[log/diff] git-style commit range over a frame\'s history: `v41..head`, `<sha>..<sha>`, `head`, or a bare `v41`/sha prefix (log: from there to head; diff: that commit against head). Defaults to the whole history for log and the last two commits for diff.'),
   chars: z.string().optional().describe('[read] character window "start-end" (0-based, end exclusive; at most 60000 per call). A frame longer than that is returned as its first page with `totalChars` and `nextChars` — pass `nextChars` back to read on. Use it for minified/single-line HTML, which `lines` cannot split.'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50") — partial read; content is hashline-annotated so a later edit stays surgical'),
   pattern: z.string().optional().describe('[ls] filter filenames (e.g. "*.html")'),
@@ -4533,6 +4537,41 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
           const result = await api('POST', '/api/fs/mv', { from, to: toPath, ...(toProjectId ? { toProjectId } : {}) }, orgHeader);
           return ok(result);
         }
+        case 'status': {
+          if (!filename) return err(new Error('status needs a frame path (a project path has no history)'));
+          const relPath = lane ? `/${layer}/${lane}/${filename}` : `/${layer}/${filename}`;
+          // projectId MUST ride the query: X-Drafted-Project is not a selector (it only
+          // accepts "none"), so without this the read resolves against whatever project
+          // the session's cursor happens to hold — and a same-named frame there answers
+          // for this one.
+          const pid = getState().projectId;
+          const result = await api('GET', `/api/fs/versions/status?path=${encodeURIComponent(relPath)}${pid ? '&projectId=' + encodeURIComponent(pid) : ''}`, undefined, orgHeader);
+          return ok(result);
+        }
+        case 'log': {
+          if (!filename) return err(new Error('log needs a frame path'));
+          const relPath = lane ? `/${layer}/${lane}/${filename}` : `/${layer}/${filename}`;
+          const [from, to] = splitRange(args.range);
+          const qs = new URLSearchParams({ path: relPath });
+          if (from) qs.set('from', from);
+          if (to) qs.set('to', to);
+          const pid = getState().projectId;
+          if (pid) qs.set('projectId', pid);
+          const result = await api('GET', `/api/fs/versions/log?${qs.toString()}`, undefined, orgHeader);
+          return ok(result);
+        }
+        case 'diff': {
+          if (!filename) return err(new Error('diff needs a frame path'));
+          const relPath = lane ? `/${layer}/${lane}/${filename}` : `/${layer}/${filename}`;
+          const [from, to] = splitRange(args.range);
+          const qs = new URLSearchParams({ path: relPath });
+          if (from) qs.set('from', from);
+          if (to) qs.set('to', to);
+          const pid = getState().projectId;
+          if (pid) qs.set('projectId', pid);
+          const result = await api('GET', `/api/fs/versions/diff?${qs.toString()}`, undefined, orgHeader);
+          return ok(result);
+        }
         case 'rm': {
           // Project-level rm = move to Trash (soft delete). Frame/lane rm still
           // deletes those items outright, but a whole project is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.24.7",
+  "version": "1.25.0",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "bin": {

package/src/shared/ai-attribution.mjs

@@ -0,0 +1,49 @@
+/**
+ * AI Act Art. 50 — ONE wording for "a machine wrote this", shared by every surface.
+ *
+ * Art. 50(1) wants a person to know they are looking at artificially generated
+ * content, and 50(2)-adjacent chat practices want it before they talk to it. A label
+ * that is spelled out is the requirement; a colour, an icon alone or a tooltip is not.
+ * So the words live here and nowhere else — the canvas frame header, the wiki footer,
+ * the skill hero, the public/share views and the Minion chat all render these, and
+ * `tests/ai-artifact-labelling.test.ts` fails if two surfaces drift apart.
+ *
+ * NOT a status and NOT a sharing state: callers render it as plain muted text (the
+ * AGENTS.md rule — colour means work status, sharing is an exempted icon+word, so an
+ * AI mark may be neither a filled chip nor a status palette entry).
+ */
+
+/** The word itself. Sentence-case, no emoji, no glyph: it has to survive being read. */
+export const AI_GENERATED_LABEL = 'AI-generated';
+
+// The Minion chat's "you are talking to an AI" sentence is NOT here: it is a translated
+// user-facing string and lives in the i18n catalogue as `minion.aiDisclosure` (en/de/nl),
+// which is the one source for copy that has to exist in three languages.
+
+/**
+ * The visible mark for an artefact whose last writer was an agent session, or null when
+ * a person wrote it (`designs.updated_by_agent` and its wiki/skill twins are NULL then,
+ * and also NULL for rows written before those columns existed — an unknown author is
+ * not an agent claim).
+ *
+ * @param {string|null|undefined} agentName the session's display name
+ * @returns {string|null}
+ */
+export function aiGeneratedLabel(agentName) {
+  const name = typeof agentName === 'string' ? agentName.trim() : '';
+  return name ? `${AI_GENERATED_LABEL} · ${name}` : AI_GENERATED_LABEL;
+}
+
+/**
+ * The hover text. Says what the label means in full, because the chip is abbreviated by
+ * space: last write, not sole author — a person may have written every earlier version.
+ *
+ * @param {string|null|undefined} agentName
+ * @returns {string}
+ */
+export function aiGeneratedTitle(agentName) {
+  const name = typeof agentName === 'string' ? agentName.trim() : '';
+  return name
+    ? `Last written by an AI agent session named "${name}" — not by a person`
+    : 'Last written by an AI agent session — not by a person';
+}

package/src/shared/commit-range.mjs

@@ -0,0 +1,13 @@
+// Git-style range syntax for a frame's commit log: `v41..head`, `<sha>..<sha>`,
+// `head`, or a bare `v41`/sha prefix. Shared rather than defined inside
+// mcp/server.mjs because importing that module opens the MCP WebSocket at module
+// scope and pins the event loop — a test that only wants this split must not pay
+// for a socket.
+export function splitRange(range) {
+  if (!range) return [null, null];
+  const raw = String(range).trim();
+  if (!raw) return [null, null];
+  const idx = raw.indexOf('..');
+  if (idx === -1) return [raw, null];
+  return [raw.slice(0, idx) || null, raw.slice(idx + 2) || null];
+}

package/src/shared/session-label.mjs

@@ -0,0 +1,44 @@
+/**
+ * A session's display name — ONE definition for the two places that must agree: the
+ * browser's session list (`GET /auth/sessions`) and the `via <name>` attribution
+ * stamped on a frame an agent wrote (`designs.updated_by_agent`).
+ *
+ * The name is `sessions.surface_name`, the label a person already sees on the agent's
+ * surface tab, because it is the only name a human and the agent both recognise. A
+ * session that never named itself — a CLI/device session, or an agent that slipped
+ * through the naming gate on an exempt route — falls back to its agent key and then to
+ * its caller class. A raw `anon:<sha256>` key is a dedup key, not a name: it is the
+ * hash of a root credential, so it is never shown.
+ *
+ * `origin` is the ONLY browser-vs-agent boundary (see src/db/schema.ts): anything that
+ * is not literally 'browser' — including NULL — is an agent.
+ */
+
+const ORIGIN_LABELS = { browser: 'Browser', device: 'CLI', agent: 'Agent' };
+
+const MAX_NAME = 120;
+
+/**
+ * @param {{ surfaceName?: string|null, agentKey?: string|null, origin?: string|null }} session
+ * @returns {string} a short human label; never empty, never a credential
+ */
+export function sessionDisplayName(session) {
+  const surface = typeof session?.surfaceName === 'string' ? session.surfaceName.trim() : '';
+  if (surface) return surface.slice(0, MAX_NAME);
+  const key = typeof session?.agentKey === 'string' ? session.agentKey.trim() : '';
+  if (key && !/^anon:/.test(key)) return key.slice(0, MAX_NAME);
+  return ORIGIN_LABELS[session?.origin] || ORIGIN_LABELS.agent;
+}
+
+/**
+ * The agent name to stamp on a frame this request writes, or null when a PERSON wrote
+ * it. Null is the meaning "a person": inventing a label here would make a human's edit
+ * read as an agent's, which is the exact confusion the column exists to end.
+ *
+ * @param {{ surfaceName?: string|null, agentKey?: string|null, origin?: string|null }} session
+ * @returns {string|null}
+ */
+export function agentAttribution(session) {
+  if (!session || session.origin === 'browser') return null;
+  return sessionDisplayName(session);
+}