portable-agent-layer 0.65.0 → 0.66.1

package/README.md

@@ -85,6 +85,8 @@ pal cli status        # check your setup
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |
+| `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
+| `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/identity.ts

@@ -0,0 +1,104 @@
+/**
+ * pal cli actor / pal cli machine — read and rename the two identities PAL keeps.
+ *
+ *   pal cli actor                 Show this actor's label and id
+ *   pal cli actor label <name>    Rename the actor — who caused a record
+ *   pal cli machine               Show this install's label and id
+ *   pal cli machine label <name>  Rename the machine — where a record was written
+ *
+ * Renaming touches no stored record: both subjects resolve a label on read, so
+ * an id already written into a thread or a reflection reads under the new name
+ * immediately. The registry entry is refreshed here so the change also travels
+ * on the next export.
+ */
+
+import {
+  actorFilePath,
+  ensureActorRegistered,
+  loadActor,
+  setActorLabel,
+} from "../hooks/lib/actor";
+import { shortId } from "../hooks/lib/identity-store";
+import {
+  ensureRegistered,
+  loadMachine,
+  machineFilePath,
+  setLabel,
+} from "../hooks/lib/machine";
+import { log } from "../targets/lib";
+
+export type IdentitySubject = "actor" | "machine";
+
+interface SubjectOps {
+  /** What the id names, for the one-line description. */
+  noun: string;
+  read(): { id: string; label: string };
+  rename(name: string): { id: string; label: string };
+  register(): void;
+  file(): string;
+}
+
+const SUBJECTS: Record<IdentitySubject, SubjectOps> = {
+  actor: {
+    noun: "who caused a record",
+    read: () => loadActor(),
+    rename: (name) => setActorLabel(name),
+    register: () => {
+      ensureActorRegistered();
+    },
+    file: () => actorFilePath(),
+  },
+  machine: {
+    noun: "where a record was written",
+    read: () => loadMachine(),
+    rename: (name) => {
+      const updated = setLabel(name);
+      return updated;
+    },
+    register: () => {
+      ensureRegistered();
+    },
+    file: () => machineFilePath(),
+  },
+};
+
+function show(subject: IdentitySubject): number {
+  const ops = SUBJECTS[subject];
+  const { id, label } = ops.read();
+  console.log(`${subject}: ${label} (${shortId(id)}) — ${ops.noun}`);
+  console.log(`  id:   ${id}`);
+  console.log(`  file: ${ops.file()}`);
+  return 0;
+}
+
+function rename(subject: IdentitySubject, name: string): number {
+  const ops = SUBJECTS[subject];
+  const before = ops.read();
+  const after = ops.rename(name);
+  ops.register();
+  if (after.label === before.label) {
+    log.info(`${subject} is already named ${after.label}`);
+    return 0;
+  }
+  log.success(`${subject} renamed: ${before.label} → ${after.label}`);
+  return 0;
+}
+
+export function runIdentity(subject: IdentitySubject, args: string[]): number {
+  const [action, ...rest] = args;
+
+  if (!action) return show(subject);
+
+  if (action === "label") {
+    const name = rest.join(" ").trim();
+    if (!name) {
+      log.error(`Usage: pal cli ${subject} label <name>`);
+      return 1;
+    }
+    return rename(subject, name);
+  }
+
+  log.error(`Unknown ${subject} action: ${action}`);
+  log.info(`Usage: pal cli ${subject} [label <name>]`);
+  return 1;
+}

package/src/cli/index.ts

@@ -244,6 +244,13 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "actor":
+    case "machine": {
+      const { runIdentity } = await import("./identity");
+      const code = runIdentity(command, args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "debug":
       cliDebug(args);
       break;
@@ -288,6 +295,8 @@ function showHelp() {
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
     pal cli analyze [--actionable]          Learning analysis: ratings, failure patterns, graduation candidates
     pal cli usage                           Summarize token usage and cost
+    pal cli actor [label <name>]            Show or rename this actor (who caused a record)
+    pal cli machine [label <name>]          Show or rename this install (where it was written)
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
@@ -1179,6 +1188,10 @@ async function install(targets: Targets) {
   await promptTelos();
   await promptAttribution();
 
+  // Registers the label loadActor derives, so it travels on the next export.
+  const { ensureActorRegistered } = await import("../hooks/lib/actor");
+  ensureActorRegistered();
+
   // Shared, target-independent state. Every target installer used to repeat these
   // identical calls; AGENTS.md in particular must exist before any target symlinks
   // to it, so it runs once here rather than once per target.

package/src/cli/migrate.ts

@@ -10,7 +10,13 @@
  * pending work without running anything.
  */
 
-import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
 import { palHome, paths } from "../hooks/lib/paths";
 import {
@@ -423,11 +429,99 @@ const v4PathsToBindings: Migration = {
   },
 };
 
+// ── v5-attribution-keys: m → machine on stored records ─────────────
+
+/**
+ * Records stamped their origin as `m`, which nobody could decode without
+ * reading the writer. The stamp is now spelled out — machine, actor, runtime,
+ * authority — and this brings historical rows onto the same schema, because a
+ * mixed schema in an append-only store is exactly what makes it unauditable
+ * later. Nothing ever read `m`, so no consumer depends on the old spelling.
+ */
+function attributionFiles(): string[] {
+  const files = [paths.reflectionsFile(), resolve(paths.state(), "threads.jsonl")];
+  const signalsDir = paths.signals();
+  if (existsSync(signalsDir)) {
+    for (const name of readdirSync(signalsDir)) {
+      if (name.endsWith(".jsonl")) files.push(resolve(signalsDir, name));
+    }
+  }
+  return files.filter((f) => existsSync(f));
+}
+
+/** Lines carrying the old key. A line already using `machine` is left alone. */
+function renameAttributionKey(raw: string): { text: string; changed: number } {
+  const lines = raw.split("\n");
+  let changed = 0;
+
+  const out = lines.map((line) => {
+    if (!line.trim()) return line;
+    let record: Record<string, unknown>;
+    try {
+      record = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return line; // a malformed line is left exactly as found
+    }
+    if (!("m" in record)) return line;
+
+    const { m, ...rest } = record;
+    changed++;
+    // `rest` spreads last so a record already carrying `machine` keeps that
+    // value and still sheds the stale `m`.
+    return JSON.stringify({ machine: m, ...rest });
+  });
+
+  return { text: out.join("\n"), changed };
+}
+
+function filesCarryingOldKey(): string[] {
+  return attributionFiles().filter(
+    (f) => renameAttributionKey(readFileSync(f, "utf-8")).changed > 0
+  );
+}
+
+const v5AttributionKeys: Migration = {
+  id: "v5-attribution-keys",
+  description: "Rename the origin stamp `m` to `machine` on stored records",
+
+  check() {
+    const stale = filesCarryingOldKey();
+    return {
+      pending: stale.length > 0,
+      detail:
+        stale.length > 0
+          ? `${stale.length} file(s) still stamp origin as \`m\``
+          : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const results: string[] = [];
+    let migrated = 0;
+
+    for (const file of filesCarryingOldKey()) {
+      const { text, changed } = renameAttributionKey(readFileSync(file, "utf-8"));
+      const name = file.replace(palHome(), "").replaceAll("\\", "/");
+      if (dryRun) {
+        results.push(`${name}: would rewrite ${changed} record(s)`);
+        migrated++;
+        continue;
+      }
+      writeFileSync(file, text, "utf-8");
+      results.push(`${name}: ${changed} record(s) rewritten`);
+      migrated++;
+    }
+
+    return { migrated, skipped: 0, results };
+  },
+};
+
 const MIGRATIONS: Migration[] = [
   v1Projects,
   v2ThreadsToIsc,
   v3EntitiesToKnowledge,
   v4PathsToBindings,
+  v5AttributionKeys,
 ];
 
 // ── Public API ────────────────────────────────────────────────────

package/src/hooks/lib/actor.ts

@@ -0,0 +1,171 @@
+/**
+ * Actor identity — who caused a record, as distinct from where it was written.
+ *
+ * A machine id answers "which install"; it deliberately never crosses an export
+ * boundary, because two installs sharing one id breaks every origin-scoped
+ * read. An actor id answers "which person", and needs the opposite treatment:
+ * the same person on a laptop and a desktop is one actor, so `actor.json` lives
+ * under memory/ where the export picks it up and the import merge adopts it on
+ * an install that has none. An install that already has an actor keeps it — the
+ * merge treats a diverged file as a conflict and leaves the local side in place.
+ *
+ * Identity alone does not attribute an action. `currentAttribution()` is the
+ * stamp a record carries: the person, the install, the agent runtime they were
+ * driving, and whether a human turn was behind the call at all.
+ */
+
+import { resolve } from "node:path";
+import { type AgentType, getActiveAgent } from "./agent";
+import {
+  type IdentityBase,
+  loadIdentity,
+  readRegistryEntries,
+  relabelIdentity,
+  resolveDisplayName,
+  shortId,
+  writeRegistryEntry as writeEntry,
+} from "./identity-store";
+import { loadMachine } from "./machine";
+import { palHome, paths } from "./paths";
+import { identity } from "./settings";
+import { isPalSpawnedInference } from "./spawn-guard";
+
+export type ActorIdentity = IdentityBase;
+
+/**
+ * Under what authority an action ran. `user` means a human turn drove it;
+ * `agent` means PAL spawned the inference itself and no human saw the call.
+ * This is the authority PAL can observe today — an approval a PAL-owned gate
+ * granted is a further distinction that gate has to introduce.
+ */
+export type Authority = "user" | "agent";
+
+/**
+ * The origin fields every attributable record carries. Spelled out rather than
+ * abbreviated: these rows are meant to be read by whoever is auditing them, and
+ * a key nobody can decode is the same as no key at all.
+ */
+export interface RecordAttribution {
+  /** Which install wrote it. */
+  machine: string;
+  /** Which person caused it. */
+  actor: string;
+  /** Which agent the actor was driving — claude, codex, cursor, copilot, opencode. */
+  runtime: AgentType;
+  /** Whether a human turn was behind the call. */
+  authority: Authority;
+}
+
+/**
+ * Unlike machine.json this sits inside memory/, so it is exported and can be
+ * adopted by a second install belonging to the same person.
+ */
+export function actorFilePath(home: string = palHome()): string {
+  return resolve(home, "memory", "actor.json");
+}
+
+function actorsDir(): string {
+  return resolve(paths.memory(), "actors");
+}
+
+/**
+ * Neutral default label, on the same reasoning as the machine default: the
+ * label travels in every exported registry entry, so a real name belongs there
+ * only once its owner has chosen to put it there.
+ */
+export function defaultActorLabel(id: string): string {
+  return `actor-${shortId(id)}`;
+}
+
+function newActor(): ActorIdentity {
+  const id = crypto.randomUUID();
+  return { id, label: defaultActorLabel(id), createdAt: new Date().toISOString() };
+}
+
+function repairActor(stored: Partial<ActorIdentity> & { id: string }): ActorIdentity {
+  return {
+    id: stored.id,
+    label: stored.label?.trim() || defaultActorLabel(stored.id),
+    createdAt: stored.createdAt || new Date().toISOString(),
+  };
+}
+
+/**
+ * The name the principal already told PAL, or nothing. The settings default of
+ * "User" names nobody, so it never becomes a label.
+ */
+function principalName(): string {
+  const name = identity().principal.name.trim();
+  return !name || name === "User" ? "" : name;
+}
+
+/**
+ * This person's identity, minted on first call and stable afterwards — across
+ * machines, once an export has carried it there.
+ *
+ * The label is derived, not stored-at-mint: while it is still the generated
+ * default, the principal's configured name wins. Seeding it once at install
+ * only held for installs that ran the seeding step, so an actor minted by an
+ * upgrade kept a neutral label forever while settings knew the name all along.
+ * Deriving on read makes the name hold on every install without a step anyone
+ * has to remember. A label the user chose is stored, and is never overridden.
+ */
+export function loadActor(home: string = palHome()): ActorIdentity {
+  const actor = loadIdentity(actorFilePath(home), newActor, repairActor);
+  if (actor.label !== defaultActorLabel(actor.id)) return actor;
+  const name = principalName();
+  return name ? { ...actor, label: name } : actor;
+}
+
+/** Rename this actor. No stored record is touched — labels resolve on read. */
+export function setActorLabel(label: string, home: string = palHome()): ActorIdentity {
+  return relabelIdentity(actorFilePath(home), loadActor(home), label);
+}
+
+export interface ActorRegistryEntry {
+  id: string;
+  label: string;
+}
+
+/** Write (or refresh) an actor's registry entry. Registry entries are exported. */
+export function writeActorEntry(entry: ActorRegistryEntry, body = ""): string {
+  return writeEntry(actorsDir(), { ...entry }, body);
+}
+
+/** Every known actor, this one and any that arrived via import. */
+export function readActorRegistry(): ActorRegistryEntry[] {
+  return readRegistryEntries(actorsDir()).map((meta) => ({
+    id: meta.id,
+    label: meta.label,
+  }));
+}
+
+/** Name for a record's actor, falling back to the short id. */
+export function actorDisplayName(id: string, registry: ActorRegistryEntry[]): string {
+  return resolveDisplayName(id, registry);
+}
+
+/** Register this actor so their label resolves on anyone else's install. */
+export function ensureActorRegistered(home: string = palHome()): ActorIdentity {
+  const actor = loadActor(home);
+  writeActorEntry({ id: actor.id, label: actor.label });
+  return actor;
+}
+
+/** Authority behind the call currently executing. */
+export function currentAuthority(): Authority {
+  return isPalSpawnedInference() ? "agent" : "user";
+}
+
+/**
+ * The origin stamp for a record written right now. Every attributable writer
+ * spreads this instead of stamping a machine id alone.
+ */
+export function currentAttribution(): RecordAttribution {
+  return {
+    machine: loadMachine().id,
+    actor: loadActor().id,
+    runtime: getActiveAgent(),
+    authority: currentAuthority(),
+  };
+}

package/src/hooks/lib/export.ts

@@ -6,6 +6,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
+import { ensureActorRegistered } from "./actor";
 import { ensureRegistered } from "./machine";
 import { palHome } from "./paths";
 
@@ -95,6 +96,7 @@ export function buildManifest(
 export function exportZip(outputPath: string): number {
   const root = palHome();
   const identity = ensureRegistered(root);
+  ensureActorRegistered(root);
   const files = collectExportFiles();
   if (files.length === 0) return 0;
 

package/src/hooks/lib/identity-store.ts

@@ -0,0 +1,138 @@
+/**
+ * Identity store — the mechanics shared by every kind of identity PAL keeps.
+ *
+ * PAL names two different subjects. A machine is the install a record came
+ * from; an actor is the person who caused it. They answer different questions
+ * and travel in opposite directions across an export boundary, but the storage
+ * problem is identical: a uuid that must never be regenerated, a label that
+ * resolves on read so a rename touches no stored record, and a registry of
+ * `<id>.md` entries so an id written on one install still reads as a name on
+ * another.
+ *
+ * Each subject supplies its own file location, its own extra fields, and its
+ * own default label. Everything below is the part that does not differ.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parse, stringify } from "./frontmatter";
+
+export interface IdentityBase {
+  id: string;
+  label: string;
+  createdAt: string;
+}
+
+/** Frontmatter of one registry entry. Every value is a string on disk. */
+export type RegistryFields = Record<string, string> & { id: string; label: string };
+
+/** Anything the display resolver can name. Extra fields are ignored. */
+export interface NameableEntry {
+  id: string;
+  label: string;
+}
+
+const SHORT_ID_LENGTH = 4;
+
+/** First segment of the uuid — enough to disambiguate two same-labelled subjects. */
+export function shortId(id: string): string {
+  return id.replaceAll("-", "").slice(0, SHORT_ID_LENGTH);
+}
+
+function hasUsableId(value: unknown): value is { id: string } {
+  const v = value as { id?: unknown } | null;
+  return typeof v?.id === "string" && v.id.length > 0;
+}
+
+/** Persist a record, creating its directory if this is the first write. */
+function saveIdentity<T extends IdentityBase>(file: string, record: T): T {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+  return record;
+}
+
+/**
+ * Read a stored identity, or mint one on first call.
+ *
+ * The id is the only irreplaceable field — discarding one orphans every record
+ * that referenced it — so a file carrying a usable id is repaired rather than
+ * regenerated, and a file that has lost its id is treated as absent.
+ */
+export function loadIdentity<T extends IdentityBase>(
+  file: string,
+  create: () => T,
+  repair: (stored: Partial<T> & { id: string }) => T
+): T {
+  if (existsSync(file)) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf-8")) as unknown;
+      if (hasUsableId(parsed)) return repair(parsed as Partial<T> & { id: string });
+    } catch {
+      /* fall through to minting a fresh identity below */
+    }
+  }
+  return saveIdentity(file, create());
+}
+
+/** Change a label without touching any stored record — labels resolve on read. */
+export function relabelIdentity<T extends IdentityBase>(
+  file: string,
+  current: T,
+  label: string
+): T {
+  return saveIdentity(file, { ...current, label: label.trim() || current.label });
+}
+
+function entryPath(dir: string, id: string): string {
+  return resolve(dir, `${id}.md`);
+}
+
+/** Write (or refresh) a registry entry. Registry entries are exported. */
+export function writeRegistryEntry(
+  dir: string,
+  fields: RegistryFields,
+  body = ""
+): string {
+  mkdirSync(dir, { recursive: true });
+  const file = entryPath(dir, fields.id);
+  const existingBody = existsSync(file) ? parse(readFileSync(file, "utf-8")).body : "";
+  writeFileSync(
+    file,
+    stringify({ ...fields, updated: new Date().toISOString() }, body || existingBody)
+  );
+  return file;
+}
+
+/**
+ * Every entry in a registry directory. Only `.md` files count, and an entry
+ * missing an id or a label is dropped — a malformed one must not hide the rest.
+ */
+export function readRegistryEntries(dir: string): RegistryFields[] {
+  mkdirSync(dir, { recursive: true });
+  const entries: RegistryFields[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".md")) continue;
+    try {
+      const { meta } = parse<Record<string, string>>(
+        readFileSync(resolve(dir, name), "utf-8")
+      );
+      if (meta.id && meta.label) entries.push(meta as RegistryFields);
+    } catch {
+      /* a malformed entry must not hide the rest of the registry */
+    }
+  }
+  return entries;
+}
+
+/**
+ * Name for a record's id. Unknown ids fall back to the short id so a record
+ * whose registry entry has not arrived yet still reads sensibly. A label shared
+ * by two subjects is suffixed rather than deduplicated — the registry is not
+ * always reachable, so uniqueness can never be enforced.
+ */
+export function resolveDisplayName(id: string, registry: NameableEntry[]): string {
+  const entry = registry.find((e) => e.id === id);
+  if (!entry) return shortId(id);
+  const sharesLabel = registry.some((e) => e.id !== id && e.label === entry.label);
+  return sharesLabel ? `${entry.label}·${shortId(id)}` : entry.label;
+}

package/src/hooks/lib/machine.ts

@@ -1,44 +1,42 @@
 /**
- * Machine identity — who this install is, and how a record's origin becomes a
- * name at display time.
- *
- * Records store the id and never the label. Resolution happens on read, so
- * renaming a machine is a one-file edit that no stored record notices, and two
- * machines sharing a label is a display concern rather than a data collision.
+ * Machine identity — which install a record came from.
  *
  * `machine.json` lives at the PAL_HOME root, outside every exported directory,
  * because importing it would give two installs one id and silently break every
- * origin-scoped read built on top of it.
+ * origin-scoped read built on top of it. Contrast with actor.ts, whose file
+ * lives under memory/ precisely so it does travel: one person on two machines
+ * is one actor, but never one machine.
+ *
+ * The storage mechanics live in identity-store.ts; this module supplies the
+ * machine-specific parts — where the file lives, the `os` field, and a label
+ * that is deliberately not the hostname.
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { resolve } from "node:path";
-import { parse, stringify } from "./frontmatter";
+import {
+  type IdentityBase,
+  loadIdentity,
+  readRegistryEntries,
+  relabelIdentity,
+  resolveDisplayName,
+  shortId,
+  writeRegistryEntry as writeEntry,
+} from "./identity-store";
 import { palHome, paths } from "./paths";
 
-export interface MachineIdentity {
-  id: string;
-  label: string;
+export interface MachineIdentity extends IdentityBase {
   os: string;
-  createdAt: string;
 }
 
-const SHORT_ID_LENGTH = 4;
+export { shortId };
 
 export function machineFilePath(home: string = palHome()): string {
   return resolve(home, "machine.json");
 }
 
 function machinesDir(): string {
-  const dir = resolve(paths.memory(), "machines");
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-/** First segment of the uuid — enough to disambiguate two same-labelled machines. */
-export function shortId(id: string): string {
-  return id.replaceAll("-", "").slice(0, SHORT_ID_LENGTH);
+  return resolve(paths.memory(), "machines");
 }
 
 /**
@@ -60,16 +58,6 @@ function newIdentity(): MachineIdentity {
   };
 }
 
-function hasUsableId(value: unknown): value is Partial<MachineIdentity> & { id: string } {
-  const v = value as Partial<MachineIdentity> | null;
-  return typeof v?.id === "string" && v.id.length > 0;
-}
-
-/**
- * Fill in whatever a stored identity is missing. Only the id is irreplaceable —
- * discarding one orphans every record that referenced it — so a file carrying a
- * usable id is repaired rather than regenerated.
- */
 function repair(stored: Partial<MachineIdentity> & { id: string }): MachineIdentity {
   return {
     id: stored.id,
@@ -85,27 +73,12 @@ function repair(stored: Partial<MachineIdentity> & { id: string }): MachineIdent
  * that referenced the old one.
  */
 export function loadMachine(home: string = palHome()): MachineIdentity {
-  const file = machineFilePath(home);
-  if (existsSync(file)) {
-    try {
-      const parsed = JSON.parse(readFileSync(file, "utf-8")) as unknown;
-      if (hasUsableId(parsed)) return repair(parsed);
-    } catch {
-      /* fall through to regeneration below */
-    }
-  }
-  const identity = newIdentity();
-  mkdirSync(home, { recursive: true });
-  writeFileSync(file, `${JSON.stringify(identity, null, 2)}\n`);
-  return identity;
+  return loadIdentity(machineFilePath(home), newIdentity, repair);
 }
 
 /** Rename this machine. No stored record is touched — labels resolve on read. */
 export function setLabel(label: string, home: string = palHome()): MachineIdentity {
-  const current = loadMachine(home);
-  const updated = { ...current, label: label.trim() || current.label };
-  writeFileSync(machineFilePath(home), `${JSON.stringify(updated, null, 2)}\n`);
-  return updated;
+  return relabelIdentity(machineFilePath(home), loadMachine(home), label);
 }
 
 export interface RegistryEntry {
@@ -114,58 +87,23 @@ export interface RegistryEntry {
   os: string;
 }
 
-function registryPath(id: string): string {
-  return resolve(machinesDir(), `${id}.md`);
-}
-
 /** Write (or refresh) a machine's registry entry. Registry entries are exported. */
 export function writeRegistryEntry(entry: RegistryEntry, body = ""): string {
-  const file = registryPath(entry.id);
-  const existingBody = existsSync(file) ? parse(readFileSync(file, "utf-8")).body : "";
-  const content = stringify(
-    {
-      id: entry.id,
-      label: entry.label,
-      os: entry.os,
-      updated: new Date().toISOString(),
-    },
-    body || existingBody
-  );
-  writeFileSync(file, content);
-  return file;
+  return writeEntry(machinesDir(), { ...entry }, body);
 }
 
 /** Every known machine, this one and any that arrived via import. */
 export function readRegistry(): RegistryEntry[] {
-  const dir = machinesDir();
-  const entries: RegistryEntry[] = [];
-  for (const name of readdirSync(dir)) {
-    if (!name.endsWith(".md")) continue;
-    try {
-      const meta = parse<Record<string, string>>(
-        readFileSync(resolve(dir, name), "utf-8")
-      ).meta;
-      if (meta.id && meta.label) {
-        entries.push({ id: meta.id, label: meta.label, os: meta.os ?? "" });
-      }
-    } catch {
-      /* a malformed entry must not hide the rest of the registry */
-    }
-  }
-  return entries;
+  return readRegistryEntries(machinesDir()).map((meta) => ({
+    id: meta.id,
+    label: meta.label,
+    os: meta.os ?? "",
+  }));
 }
 
-/**
- * Name for a record's origin id. Unknown ids fall back to the short id so a
- * record from a machine whose entry has not arrived yet still reads sensibly.
- * A label shared by two machines is suffixed rather than deduplicated — the
- * registry is not always reachable, so uniqueness can never be enforced.
- */
+/** Name for a record's origin machine, falling back to the short id. */
 export function displayName(id: string, registry: RegistryEntry[]): string {
-  const entry = registry.find((e) => e.id === id);
-  if (!entry) return shortId(id);
-  const sharesLabel = registry.some((e) => e.id !== id && e.label === entry.label);
-  return sharesLabel ? `${entry.label}·${shortId(id)}` : entry.label;
+  return resolveDisplayName(id, registry);
 }
 
 /** Register this install so its label can be resolved on any machine. */

package/src/hooks/lib/relationship.ts

@@ -47,16 +47,26 @@ function dedup(notes: RelationshipNote[], filepath: string): RelationshipNote[]
   }
 }
 
-/** Append notes to today's relationship file */
-export function appendNotes(notes: RelationshipNote[], sessionId?: string): void {
-  if (notes.length === 0) return;
+/** What an append actually did — `written` is the count after deduplication. */
+export interface AppendResult {
+  file: string;
+  written: number;
+}
 
+/**
+ * Append notes to today's relationship file. Reports the file and the number of
+ * notes that survived deduplication, which is what a caller must report rather
+ * than the count it passed in.
+ */
+export function appendNotes(notes: RelationshipNote[], sessionId?: string): AppendResult {
   const filepath = dailyFilePath(new Date());
+  if (notes.length === 0) return { file: filepath, written: 0 };
+
   const today = new Date().toISOString().slice(0, 10);
 
   // Deduplicate against existing content
   const fresh = dedup(notes, filepath);
-  if (fresh.length === 0) return;
+  if (fresh.length === 0) return { file: filepath, written: 0 };
 
   const lines: string[] = [];
 
@@ -81,6 +91,7 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): void
 
   const existing = existsSync(filepath) ? readFileSync(filepath, "utf-8") : "";
   writeFileSync(filepath, existing + lines.join("\n"), "utf-8");
+  return { file: filepath, written: fresh.length };
 }
 
 /** Load notes from the last N days as a single string */

package/src/hooks/lib/signals.ts

@@ -1,6 +1,6 @@
 import { appendFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadMachine } from "./machine";
+import { currentAttribution } from "./actor";
 import { paths } from "./paths";
 import { now } from "./time";
 
@@ -15,7 +15,7 @@ function emitSignal(
   filename: string,
   data: { type: string; [key: string]: unknown }
 ): void {
-  const signal: Signal = { ts: now(), m: loadMachine().id, ...data };
+  const signal: Signal = { ts: now(), ...currentAttribution(), ...data };
   const filepath = resolve(paths.signals(), filename);
   appendFileSync(filepath, `${JSON.stringify(signal)}\n`);
 }

package/src/tools/agent/algorithm-reflect.ts

@@ -15,17 +15,16 @@
 
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
+import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
 import { encodeAnchor } from "../../hooks/lib/anchor";
-import { loadMachine } from "../../hooks/lib/machine";
 import { paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
 
 // ── Types ──
 
-interface AlgorithmReflection {
+interface AlgorithmReflection extends RecordAttribution {
   timestamp: string;
   cwd: string;
-  m: string;
   task: string;
   criteria_count: number;
   criteria_passed: number;
@@ -64,7 +63,7 @@ export function buildReflection(input: {
   return {
     timestamp: new Date().toISOString(),
     cwd: encodeAnchor(process.cwd()),
-    m: loadMachine().id,
+    ...currentAttribution(),
     task: input.task,
     criteria_count: input.criteria_count ?? 0,
     criteria_passed: input.criteria_passed ?? 0,
@@ -156,7 +155,11 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
   });
 
   const result = appendReflection(reflection);
-  emit.ok(result.message);
+  emit.receipt(result.path, {
+    passed: reflection.criteria_passed,
+    of: reflection.criteria_count,
+    scope: reflection.scope,
+  });
 }
 
 if (import.meta.main) run();

package/src/tools/agent/handoff-note.ts

@@ -39,10 +39,12 @@ function readHandoffs(): Record<string, HandoffEntry> {
   }
 }
 
-function writeHandoffs(handoffs: Record<string, HandoffEntry>): void {
+/** Returns how many entries survived the trim, which is what the receipt reports. */
+function writeHandoffs(handoffs: Record<string, HandoffEntry>): number {
   const entries = Object.entries(handoffs);
   const trimmed = entries.length > 20 ? Object.fromEntries(entries.slice(-20)) : handoffs;
   writeFileSync(handoffPath(), JSON.stringify(trimmed, null, 2), "utf-8");
+  return Object.keys(trimmed).length;
 }
 
 function writeHandoffNote(
@@ -50,7 +52,7 @@ function writeHandoffNote(
   title: string,
   text: string,
   done: boolean
-): { success: boolean; message: string } {
+): { file: string; status: HandoffEntry["status"]; kept: number } {
   const handoffs = readHandoffs();
   handoffs[cwd] = {
     timestamp: new Date().toISOString(),
@@ -60,11 +62,8 @@ function writeHandoffNote(
     artifacts: [],
     source: "deliberate",
   };
-  writeHandoffs(handoffs);
-  return {
-    success: true,
-    message: done ? "Handoff cleared (marked completed)" : "Handoff note written",
-  };
+  const kept = writeHandoffs(handoffs);
+  return { file: handoffPath(), status: handoffs[cwd].status, kept };
 }
 
 function run() {
@@ -103,7 +102,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
       values.text || "",
       true
     );
-    emit.ok(result.message);
+    emit.receipt(result.file, { status: result.status, entries: result.kept });
     process.exit(0);
   }
 
@@ -113,7 +112,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
   }
 
   const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
-  emit.ok(result.message);
+  emit.receipt(result.file, { status: result.status, entries: result.kept });
 }
 
 if (import.meta.main) run();

package/src/tools/agent/relationship-note.ts

@@ -82,9 +82,8 @@ Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
     notes.push({ type: "Session" as const, text: values.b });
   }
 
-  appendNotes(notes);
-
-  emit.ok(`Relationship note written (${notes.length})`);
+  const { file, written } = appendNotes(notes);
+  emit.receipt(file, { written, deduped: notes.length - written });
 }
 
 if (import.meta.main) run();

package/src/tools/agent/thread.ts

@@ -14,17 +14,16 @@
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
 import { encodeAnchor } from "../../hooks/lib/anchor";
-import { loadMachine } from "../../hooks/lib/machine";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
 
 // ── Types ──
 
-export interface Thread {
+export interface Thread extends RecordAttribution {
   id: string;
   cwd: string;
-  m: string;
   title: string;
   context: string;
   status: "open" | "resolved";
@@ -70,7 +69,7 @@ export function addThread(title: string, context: string): Thread {
   const thread: Thread = {
     id: generateId(),
     cwd: encodeAnchor(process.cwd()),
-    m: loadMachine().id,
+    ...currentAttribution(),
     title,
     context,
     status: "open",
@@ -143,7 +142,11 @@ Usage:
       process.exit(1);
     }
     const thread = addThread(values.title, values.context ?? "");
-    emit.data(`Added with id ${thread.id}`);
+    emit.receipt(threadsPath(), {
+      id: thread.id,
+      title: thread.title,
+      status: thread.status,
+    });
   }
 
   if (cmd === "resolve") {
@@ -152,8 +155,15 @@ Usage:
       process.exit(1);
     }
     const resolved = resolveThread(values.id);
-    if (resolved.success) emit.ok(resolved.message ?? "Thread resolved");
-    else emit.data(JSON.stringify(resolved, null, 2));
+    if (!resolved.success) {
+      console.error(resolved.message);
+      process.exit(1);
+    }
+    emit.receipt(threadsPath(), {
+      id: values.id,
+      status: "resolved",
+      title: resolved.thread?.title,
+    });
   }
 
   if (cmd === "list") {

package/src/tools/agent/wisdom-frame.ts

@@ -234,7 +234,7 @@ Examples:
 
   const cliType = (values.type || "evolution") as ObservationType;
   const result = updateFrame(values.domain, values.observation, cliType);
-  emit.ok(result.message);
+  emit.receipt(result.framePath, { domain: result.domain, type: result.type });
 }
 
 if (import.meta.main) run();

package/src/tools/lib/emit.ts

@@ -4,13 +4,25 @@
  * confirmations are pure noise that costs context tokens; a human at a TTY wants
  * them. Gate on the TTY signal, with PAL_VERBOSE / PAL_QUIET as explicit overrides.
  *
- *   data()  requested payload — ALWAYS emitted (list output, reports, results)
- *   ok()    success confirmation / progress — only at a TTY or under PAL_VERBOSE
+ *   data()     requested payload — ALWAYS emitted (list output, reports, results)
+ *   receipt()  proof a write landed — ALWAYS emitted (see below)
+ *   ok()       success confirmation / progress — only at a TTY or under PAL_VERBOSE
  *
  * Errors stay on console.error (stderr) + a non-zero exit — always surfaced,
  * independent of this gate.
+ *
+ * Why receipt() is not gated: a state-changing call's confirmation is its
+ * payload, not progress chatter. Without it a caller cannot tell what landed or
+ * where, and re-reads the file to find out — which costs far more context than
+ * the one line the gate saved. The receipt reports what was actually written,
+ * so a writer that deduplicates or trims must report the real count rather than
+ * what it was handed. `no-silent-write` in klint.rules.ts enforces that every
+ * tool writing to disk emits one.
  */
 
+import { relative } from "node:path";
+import { palHome } from "../../hooks/lib/paths";
+
 function isVerbose(): boolean {
   if (process.env.PAL_QUIET === "1") return false;
   if (process.env.PAL_VERBOSE === "1") return true;
@@ -21,6 +33,16 @@ function line(stream: { write: (s: string) => void }, text: string): void {
   stream.write(text.endsWith("\n") ? text : `${text}\n`);
 }
 
+/**
+ * Paths are reported relative to PAL_HOME so a receipt reads the same on every
+ * machine, and never discloses an absolute home path. A file outside PAL_HOME
+ * keeps its own path — a "../.." chain would name nothing useful.
+ */
+function homeRelative(file: string): string {
+  const rel = relative(palHome(), file).replaceAll("\\", "/");
+  return rel && !rel.startsWith("..") ? rel : file.replaceAll("\\", "/");
+}
+
 export const emit = {
   data(text: string): void {
     line(process.stdout, text);
@@ -28,4 +50,11 @@ export const emit = {
   ok(text: string): void {
     if (isVerbose()) line(process.stdout, text);
   },
+  /** Proof that a write landed: the file it went to, plus what the operation produced. */
+  receipt(file: string, extra: Record<string, unknown> = {}): void {
+    line(
+      process.stdout,
+      JSON.stringify({ ok: true, wrote: homeRelative(file), ...extra })
+    );
+  },
 };

package/src/tools/relationship-reflect.ts

@@ -454,7 +454,12 @@ Output:
     const report = formatReport(period, notes, ratings, opinionChanges);
     const filepath = writeReport(report, period);
     setLastReflectDate(new Date().toISOString().slice(0, 10));
-    emit.ok(`\nCreated reflection report: ${filepath}`);
+    emit.receipt(filepath, {
+      period,
+      notes: notes.length,
+      ratings: ratings.length,
+      opinionChanges: opinionChanges.length,
+    });
 
     const opinions = readOpinions();
     const high = opinions.filter((o) => o.confidence >= 0.85);