claude-memory-admin 1.10.1 → 1.11.0

package/public/views/header.mjs

@@ -23,6 +23,7 @@ const NAVIGATION = [
       { id: 'instructions', label: 'Instructions' },
       { id: 'settings', label: 'Settings' },
       { id: 'cost', label: 'Cost' },
+      { id: 'attribution', label: 'Attribution' },
       { id: 'sessions', label: 'Sessions' },
       { id: 'tools', label: 'Tools' },
     ],
@@ -41,6 +42,7 @@ function segmentVisible(tab, segment, store) {
   }
   if (segment === 'instructions') return global || hasProjectDir(store);
   if (segment === 'cost') return global;
+  if (segment === 'attribution') return global;
   if (segment === 'tools') return state.tools.length > 0;
   if (global) return false;
   if (segment === 'sessions') return Boolean(store.sessions?.count);
@@ -56,11 +58,17 @@ export const costProblems = () => {
   ];
 };
 
+export const attributionProblems = () => state.aux.attribution?.settings?.problems || [];
+
 function segmentBadge(id) {
   if (id === 'cost') {
     const problems = costProblems();
     return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
   }
+  if (id === 'attribution') {
+    const problems = attributionProblems();
+    return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
+  }
   if (id === 'instructions') {
     const problems = state.aux.instructions?.problems || [];
     return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
@@ -107,6 +115,7 @@ function tabBadge(tab, store) {
     ...(state.aux.instructions?.problems || []),
     ...(state.aux.settings?.problems || []),
     ...costProblems(),
+    ...attributionProblems(),
   ];
   return problems.length ? { badge: String(problems.length), tone: worstSeverity(problems) } : {};
 }

package/public/views/issue.mjs

@@ -258,5 +258,29 @@ export function renderIssue(item, memories) {
     );
   }
 
+  if (item.kind === 'agent-memory-inert') {
+    return issue(
+      'Auto memory is off, so this store is frozen',
+      `subagent memory is part of auto memory${item.setBy ? `, and ${item.setBy} turns it off` : ' and it is turned off'}. The memory: field on ${item.agentName} has no effect while that is the case: the agent starts with no memory instructions and no file tools, so nothing here is read and nothing new is written.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-orphan') {
+    return issue(
+      'Nothing declares this store any more',
+      `${item.defined ? `${item.agentName} exists but no longer carries a memory: field` : `no agent named ${item.agentName} was found in any scope`}. A store is created by that field and outlives it, so this directory is still holding what it learned and no session will read it again.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-scope-mismatch') {
+    return issue(
+      `${item.agentName} keeps its memory in the ${item.declaredScope} scope now`,
+      `this store is the ${item.scope} one${item.declaredBy ? `, but ${item.declaredBy} declares memory: ${item.declaredScope}` : ''}. The live store is the ${item.declaredScope} one; this is what the agent wrote before the field changed.`,
+      { bad },
+    );
+  }
+
   return issue(item.kind, JSON.stringify(item));
 }

package/public/views/stores.mjs

@@ -11,6 +11,26 @@ function storeSubtitle(store) {
   return `${scope} · ${store.sublabel}`;
 }
 
+function agentMarker(store) {
+  if (!String(store.kind).startsWith('agent-') || !store.linkage) return null;
+  if (store.inert) {
+    return { text: 'inert', title: `Auto memory is off${store.inertBy ? ` (${store.inertBy})` : ''}, so the memory: field has no effect and this store is frozen.` };
+  }
+  if (store.linked) return null;
+  if (store.declaredScope) {
+    return {
+      text: 'moved',
+      title: `${store.agentName} now declares memory: ${store.declaredScope}, so the live store is elsewhere and this one is stale.`,
+    };
+  }
+  return {
+    text: 'orphan',
+    title: store.defined
+      ? `${store.agentName} exists but declares no memory: field any more, so nothing loads this store.`
+      : `No agent named ${store.agentName} was found in any scope, so nothing loads this store.`,
+  };
+}
+
 function issueTitle(store) {
   const parts = [];
   if (store.issueCount) parts.push(`${store.issueCount} to fix in Cleanup`);
@@ -32,6 +52,7 @@ function storeButton(store) {
   const global = store.kind === 'global';
   const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
+  const marker = agentMarker(store);
   const active = state.activeSessions.filter((s) => s.storeId === store.id);
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
@@ -43,6 +64,7 @@ function storeButton(store) {
       node('span', { class: ui.storeName, text: store.label }),
       active.length ? node('span', { class: ui.dot('ok'), title: activeTitle(active) }) : null,
       off ? node('span', { class: ui.offMarker, text: 'off', title: 'Auto memory is disabled for this project' }) : null,
+      marker ? node('span', { class: ui.offMarker, text: marker.text, title: marker.title }) : null,
       global ? null : node('span', { class: ui.storeCount, text: store.hasMemoryDir ? String(store.memoryCount) : '-' }),
     ]),
     node('span', { class: ui.storePath, text: storeSubtitle(store) }),

package/server.mjs

@@ -13,7 +13,8 @@ import { buildStore } from './src/model.mjs';
 import { resolveGlobalInstructions, resolveInstructions, summarise } from './src/instructions.mjs';
 import { settingsReport, summariseSettings } from './src/settings.mjs';
 import { costReport, writeUserSetting } from './src/cost.mjs';
-import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAgents, setAgentField } from './src/agents.mjs';
+import { attributionReport, writeAttributionSetting } from './src/attribution.mjs';
+import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAllAgents, setAgentField } from './src/agents.mjs';
 import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
@@ -140,6 +141,67 @@ const VERSION = (() => {
   }
 })();
 
+/**
+ * Every agent definition on the machine: the user directory plus the agents
+ * directory of each repository auto memory has already resolved a path for.
+ * Nothing here guesses at a repository that was not confirmed somewhere else.
+ */
+function allAgents() {
+  const projectPaths = listStores(ROOT)
+    .filter((store) => store.kind === 'auto' && store.pathExists)
+    .flatMap((store) => [store.path, ...(store.workingDirs || [])]);
+  return listAllAgents({ projectPaths });
+}
+
+/** Each subagent memory store next to the definition that asks for it, for the agents panel. */
+function agentStoreLinks() {
+  return listStores(ROOT)
+    .filter((store) => String(store.kind).startsWith('agent-'))
+    .map((store) => ({
+      id: store.id,
+      kind: store.kind,
+      agentName: store.agentName,
+      projectPath: store.projectPath,
+      memoryCount: store.memoryCount,
+      declaredBy: store.declaredBy ?? null,
+      declaredScope: store.declaredScope ?? null,
+      linked: Boolean(store.linked),
+      defined: Boolean(store.defined),
+      inert: Boolean(store.inert),
+      inertBy: store.inertBy ?? null,
+    }));
+}
+
+/**
+ * Hand the address to whatever opens a URL here, and never let that decide
+ * whether the server runs.
+ *
+ * `start` is a cmd.exe builtin rather than a program, so spawning it by name
+ * fails on Windows; the documented form is `cmd /c start "" <url>`, where the
+ * empty string is the window title `start` would otherwise read the URL as. On
+ * Linux `xdg-open` is simply missing on a minimal install and inside some
+ * containers. Either way the failure arrives as an async 'error' event, which
+ * with no listener is an uncaught exception that would take down a server that
+ * had already printed its address and was working perfectly well.
+ */
+function openBrowser(address) {
+  const [command, args] = process.platform === 'darwin'
+    ? ['open', [address]]
+    : process.platform === 'win32'
+      ? [process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', 'start', '""', address.replace(/&/g, '^&')]]
+      : ['xdg-open', [address]];
+
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => {
+      console.log('Could not open a browser automatically - open the address above yourself.');
+    });
+    child.unref();
+  } catch {
+    console.log('Could not open a browser automatically - open the address above yourself.');
+  }
+}
+
 function storeProjectDir(store) {
   // The global store is the user scope itself, which no project owns.
   if (store.kind === 'global') return null;
@@ -160,7 +222,7 @@ function storeProjectDir(store) {
  * frontmatter fields in a named file inside ~/.claude/agents. Neither can reach
  * an instruction file, which is what the rest of this guard exists to protect.
  */
-const GLOBAL_WRITE_ACTIONS = new Set(['cost/setting', 'cost/agent']);
+const GLOBAL_WRITE_ACTIONS = new Set(['cost/setting', 'cost/agent', 'attribution/setting']);
 
 export function refuseWritesToGlobal(store, method, action = null) {
   if (store.kind !== 'global' || method === 'GET') return;
@@ -328,13 +390,24 @@ async function handleApi(req, res, url) {
     return sendJson(res, 400, { error: 'The cost settings are user-scope, and are edited from the Global entry.' });
   }
 
+  // The Attribution segment. User scope only, for the same reason as Cost:
+  // it edits ~/.claude/settings.json, which applies to every session.
+  if ((action === 'attribution' || action.startsWith('attribution/')) && store.kind !== 'global') {
+    return sendJson(res, 400, { error: 'The attribution settings are user-scope, and are edited from the Global entry.' });
+  }
+
   if (action === 'cost' && req.method === 'GET') {
     return sendJson(res, 200, {
       settings: costReport(),
-      agents: listAgents(),
+      // Project-scope definitions come along read-only: an agent with
+      // `memory: project` lives in a repository rather than in the user
+      // directory, and leaving it out would show its memory store as belonging
+      // to no agent at all.
+      agents: allAgents(),
       agentsDir: AGENTS_DIR,
       agentsDirExists: agentsDirExists(),
       agentFields: AGENT_FIELDS,
+      agentStores: agentStoreLinks(),
     });
   }
 
@@ -346,8 +419,23 @@ async function handleApi(req, res, url) {
 
   if (action === 'cost/agent' && req.method === 'POST') {
     const body = await readBody(req);
-    const agents = setAgentField(body.file, body.field, body.value ?? null);
-    return sendJson(res, 200, { agents, agentsDir: AGENTS_DIR, agentsDirExists: agentsDirExists() });
+    setAgentField(body.file, body.field, body.value ?? null);
+    return sendJson(res, 200, {
+      agents: allAgents(),
+      agentsDir: AGENTS_DIR,
+      agentsDirExists: agentsDirExists(),
+      agentStores: agentStoreLinks(),
+    });
+  }
+
+  if (action === 'attribution' && req.method === 'GET') {
+    return sendJson(res, 200, { settings: attributionReport() });
+  }
+
+  if (action === 'attribution/setting' && req.method === 'POST') {
+    const body = await readBody(req);
+    writeAttributionSetting(body.key, body.value ?? null);
+    return sendJson(res, 200, { settings: attributionReport() });
   }
 
   if (action === 'delete-preview' && req.method === 'POST') {
@@ -484,10 +572,7 @@ export function startServer({ port, root, open = true } = {}) {
     const address = `http://localhost:${listenPort}`;
     console.log(`Memory Admin  ->  ${address}`);
     console.log(`Reading       ->  ${ROOT}`);
-    if (open && !process.env.NO_OPEN) {
-      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, [address], { stdio: 'ignore', detached: true }).unref();
-    }
+    if (open && !process.env.NO_OPEN) openBrowser(address);
   });
   return server;
 }

package/src/agents.mjs

@@ -1,9 +1,12 @@
-// User-scope subagent definitions: ~/.claude/agents/*.md.
+// Subagent definitions: agents/*.md, in the user scope and in each repository.
 //
-// Not to be confused with ~/.claude/agent-memory (src/stores.mjs), which is what
-// those agents *remember*. This module is about what they *are*: a markdown file
-// whose frontmatter names the agent and, optionally, pins the model and effort
-// it runs at. Pinning a summariser to Haiku while a reviewer stays on Opus is the
+// Not to be confused with agent-memory (src/stores.mjs), which is what those
+// agents *remember*. This module is about what they *are*: a markdown file whose
+// frontmatter names the agent and, optionally, pins the model and effort it runs
+// at, and declares with `memory:` whether it keeps a memory directory at all.
+// That last field is the link between the two: a store exists because some file
+// here asked for it, and a store no file asks for any more is a store nothing
+// loads. Pinning a summariser to Haiku while a reviewer stays on Opus is the
 // finer-grained version of the CLAUDE_CODE_SUBAGENT_MODEL switch in src/cost.mjs,
 // which - worth remembering when both are set - outranks everything here.
 //
@@ -12,13 +15,21 @@
 // somebody wrote on purpose, and this tool has no view on it.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
+import { canonicalPath, configPath } from './config.mjs';
 import { parseFrontmatter } from './parse.mjs';
 import { writeFileAtomic } from './mutate.mjs';
 
-export const AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+export const AGENTS_DIR = configPath('agents');
+export const PROJECT_AGENTS_DIR = path.join('.claude', 'agents');
+
+/** The scopes `memory:` accepts, and the store kind each one produces. */
+export const MEMORY_SCOPES = {
+  user: 'agent-user',
+  project: 'agent-project',
+  local: 'agent-local',
+};
 
 const MODEL_ID = /^claude-[A-Za-z0-9._[\]-]+$/;
 
@@ -55,6 +66,7 @@ export const AGENT_PROBLEM_SEVERITY = {
   'name-mismatch': 'warn',
   'unknown-model': 'warn',
   'unknown-effort': 'warn',
+  'unknown-memory-scope': 'warn',
 };
 
 function known(field, value) {
@@ -92,9 +104,9 @@ export function safeAgentPath(dir, file) {
   return full;
 }
 
-function describeAgent(dir, file) {
+function describeAgent(dir, file, { scope = 'user', writable = true, projectPath = null } = {}) {
   const full = path.join(dir, file);
-  const stem = file.replace(/\.md$/, '');
+  const stem = path.basename(file).replace(/\.md$/, '');
 
   let text;
   try {
@@ -102,11 +114,15 @@ function describeAgent(dir, file) {
   } catch (err) {
     return {
       file,
+      scope,
+      writable: false,
+      projectPath,
       name: stem,
       description: '',
       tools: '',
       model: null,
       effort: null,
+      memory: null,
       bytes: 0,
       problems: [{ kind: 'no-frontmatter', severity: 'bad', detail: err.message }],
     };
@@ -117,6 +133,7 @@ function describeAgent(dir, file) {
   const name = scalar('name') || stem;
   const model = scalar('model') || null;
   const effort = scalar('effort') || null;
+  const memory = scalar('memory') || null;
 
   const problems = [];
   const flag = (kind, detail) => problems.push({ kind, severity: AGENT_PROBLEM_SEVERITY[kind], detail });
@@ -129,26 +146,39 @@ function describeAgent(dir, file) {
     if (scalar('name') && scalar('name') !== stem) flag('name-mismatch', `Named "${scalar('name')}" in a file called "${file}".`);
     if (model && !known('model', model)) flag('unknown-model', `model: ${model} is neither an alias nor a claude- model name.`);
     if (effort && !known('effort', effort)) flag('unknown-effort', `effort: ${effort} is not one of low, medium, high, xhigh or max.`);
+    if (memory && !Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory)) {
+      flag('unknown-memory-scope', `memory: ${memory} is not one of user, project or local, so this agent keeps no memory directory.`);
+    }
   }
 
   return {
     file,
+    scope,
+    // Only a plain .md at the top of the user directory is rewritable: writes go
+    // through safeAgentPath, which takes a bare basename, and nothing here has
+    // any business editing a file inside somebody's repository.
+    writable: writable && file === path.basename(file),
+    projectPath,
     name,
     description: scalar('description'),
     tools: scalar('tools'),
     model,
     effort,
+    memory: memory && Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory) ? memory : null,
+    memoryRaw: memory,
     bytes: Buffer.byteLength(text, 'utf8'),
     problems,
   };
 }
 
 /**
- * Every user-scope agent definition. A directory that is not there is the
- * ordinary state of a machine whose owner has never written one, not a failure,
- * so it answers with an empty list.
+ * Every .md under an agents directory, including the subfolders people use to
+ * group them. Claude Code scans both agent roots recursively and identifies an
+ * agent by its `name` rather than by where the file sits, so a scan that stopped
+ * at the top level would miss agents that are running.
  */
-export function listAgents({ dir = AGENTS_DIR } = {}) {
+function agentFiles(dir, prefix = '', depth = 0) {
+  if (depth > 4) return [];
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -156,12 +186,54 @@ export function listAgents({ dir = AGENTS_DIR } = {}) {
     return [];
   }
 
-  return entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.'))
-    .map((entry) => describeAgent(dir, entry.name))
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...agentFiles(path.join(dir, entry.name), rel, depth + 1));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(rel);
+  }
+  return files;
+}
+
+/**
+ * Every user-scope agent definition. A directory that is not there is the
+ * ordinary state of a machine whose owner has never written one, not a failure,
+ * so it answers with an empty list.
+ */
+export function listAgents({ dir = AGENTS_DIR } = {}) {
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'user', writable: true }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Project-scope definitions, from <repo>/.claude/agents. These are read and
+ * never written: they belong to a repository somebody else may share, and an
+ * agent with `memory: project` is normally defined here rather than in the user
+ * scope, so leaving them out would orphan the very stores this exists to explain.
+ */
+export function listProjectAgents(projectPath, { relative = PROJECT_AGENTS_DIR } = {}) {
+  if (!projectPath || !path.isAbsolute(projectPath)) return [];
+  const dir = path.join(projectPath, relative);
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'project', writable: false, projectPath }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/** Every definition on the machine this tool can see: user scope plus each repository. */
+export function listAllAgents({ dir = AGENTS_DIR, projectPaths = [] } = {}) {
+  const agents = listAgents({ dir });
+  const seen = new Set();
+  for (const projectPath of projectPaths) {
+    const key = canonicalPath(projectPath || '');
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    agents.push(...listProjectAgents(projectPath));
+  }
+  return agents;
+}
+
 /** Whether the directory itself exists, which is what tells an empty list from a missing one. */
 export function agentsDirExists({ dir = AGENTS_DIR } = {}) {
   try {
@@ -205,7 +277,11 @@ function insertionIndex(block) {
  * that changed, never re-emit the document from a parse of it.
  */
 export function rewriteAgentField(text, field, value) {
-  const lines = text.split('\n');
+  // Rejoin with whatever the file already used. A checkout on Windows is CRLF
+  // throughout, and splitting on \n then rejoining with it would leave every
+  // line this function did not touch ending \r\n and the one it did ending \n.
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
   if (lines[0]?.trim() !== '---') {
     throw new Error('This file has no frontmatter block, so there is nothing to set.');
   }
@@ -230,7 +306,7 @@ export function rewriteAgentField(text, field, value) {
     block[at] = `${field}: ${value}`;
   }
 
-  return [lines[0], ...block, ...lines.slice(end)].join('\n');
+  return [lines[0], ...block, ...lines.slice(end)].join(eol);
 }
 
 function normaliseAgentValue(field, value) {

package/src/attribution.mjs

@@ -0,0 +1,152 @@
+// The `attribution` block in ~/.claude/settings.json: the trailer Claude Code
+// adds to commits, the line it adds to PR descriptions, and the session URL it
+// appends to cloud/Remote Control commits. The second panel this tool writes to
+// a settings file, alongside the Cost panel in cost.mjs.
+//
+// Unlike Cost's keys, `commit` and `pr` take arbitrary text rather than one of
+// a handful of options, so there is no fixed option list here: a value is either
+// unset (default text), `false` (hidden), or any string (a replacement).
+// `sessionUrl` only ever takes `false` - there is no custom text for it.
+
+import { setPath } from './cost.mjs';
+import { writeFileAtomic } from './mutate.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  SETTINGS_SEVERITY,
+  USER_SETTINGS,
+  readJsonDetailed,
+  readPath,
+  settingsCandidates,
+} from './settings.mjs';
+
+export const ATTRIBUTION_KEYS = [
+  {
+    key: 'commit',
+    path: ['attribution', 'commit'],
+    label: 'attribution.commit',
+    title: 'Commit trailer',
+    detail: 'The co-authored-by trailer Claude Code adds to commits it makes. Hide it, or replace it with your own text.',
+    kind: 'text-or-hide',
+  },
+  {
+    key: 'pr',
+    path: ['attribution', 'pr'],
+    label: 'attribution.pr',
+    title: 'Pull request line',
+    detail: 'The attribution line Claude Code adds to pull request descriptions it writes. Hide it, or replace it with your own text.',
+    kind: 'text-or-hide',
+  },
+  {
+    key: 'sessionUrl',
+    path: ['attribution', 'sessionUrl'],
+    label: 'attribution.sessionUrl',
+    title: 'Session link',
+    detail: 'The claude.ai session link Claude Code appends to commits made from the cloud or Remote Control. It cannot be replaced, only omitted.',
+    kind: 'hide-only',
+  },
+];
+
+/**
+ * What a value means once it is checked: a string or `false` to write, or null
+ * to remove the key. Anything the key does not accept throws rather than being
+ * coerced, because a coerced value would be written to the user's settings file.
+ */
+export function normaliseAttributionValue(descriptor, value) {
+  if (value === null || value === undefined) return null;
+
+  if (descriptor.kind === 'hide-only') {
+    if (value === false) return false;
+    throw new Error(`${descriptor.label} only accepts false (to hide it) or unset.`);
+  }
+
+  if (value === false) return false;
+  if (typeof value !== 'string') {
+    throw new Error(`${descriptor.label} takes a string or false, not ${Array.isArray(value) ? 'a list' : typeof value}.`);
+  }
+  return value;
+}
+
+/**
+ * Every layer's value for all three keys, strongest first, in the same shape
+ * the Cost report uses so the two render identically.
+ */
+export function attributionReport(options = {}) {
+  const { userFile = USER_SETTINGS, ...target } = options;
+
+  const reads = settingsCandidates({ ...target, userFile }).map((candidate) => ({
+    ...candidate,
+    ...readJsonDetailed(candidate.file),
+  }));
+  const layers = reads.map(({ scope, file, status, error }) => ({ scope, file, status, error }));
+
+  const keys = ATTRIBUTION_KEYS.map((descriptor) => {
+    const values = reads
+      .filter((read) => read.status === 'ok' && readPath(read.data, descriptor.path) !== undefined)
+      .map((read) => ({
+        scope: read.scope,
+        file: read.file,
+        value: readPath(read.data, descriptor.path),
+        wins: false,
+      }));
+    if (values.length) values[0].wins = true;
+    const winner = values[0] || null;
+
+    return {
+      key: descriptor.key,
+      label: descriptor.label,
+      title: descriptor.title,
+      detail: descriptor.detail,
+      kind: descriptor.kind,
+      values,
+      effective: winner ? { value: winner.value, scope: winner.scope, file: winner.file } : null,
+      shadowedByStronger: Boolean(winner && winner.scope !== 'user'),
+    };
+  });
+
+  const userRead = reads.find((read) => read.file === userFile);
+  const problems = layers
+    .filter((layer) => layer.status !== 'ok' && layer.status !== 'absent')
+    .map((layer) => ({
+      kind: layer.status,
+      severity: SETTINGS_SEVERITY[layer.status] || 'warn',
+      scope: layer.scope,
+      file: layer.file,
+      detail: layer.error,
+    }));
+
+  return {
+    keys,
+    layers,
+    problems,
+    userFile,
+    writable: !userRead || userRead.status === 'ok' || userRead.status === 'absent',
+  };
+}
+
+/**
+ * Write one key to the user settings file, atomically, and answer with the value
+ * that landed. A file that exists but does not parse is refused outright.
+ */
+export function writeAttributionSetting(key, value, options = {}) {
+  const { file = USER_SETTINGS } = options;
+
+  const descriptor = ATTRIBUTION_KEYS.find((entry) => entry.key === key);
+  if (!descriptor) throw new Error(`"${key}" is not a setting this tool writes.`);
+
+  const next = normaliseAttributionValue(descriptor, value);
+
+  const read = readJsonDetailed(file);
+  if (read.status !== 'ok' && read.status !== 'absent') {
+    throw new Error(`Refusing to write ${file}: ${read.error || read.status}. Rewriting a file this tool cannot parse would drop the settings it cannot see, so fix the file by hand first.`);
+  }
+
+  const data = read.status === 'ok' ? read.data : {};
+  setPath(data, descriptor.path, next);
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  writeFileAtomic(path.dirname(file), path.basename(file), `${JSON.stringify(data, null, 2)}\n`);
+
+  return next;
+}