From bf893c67a7689ba0d310e3e8868674b5d0dbc807 Mon Sep 17 00:00:00 2001
From: schickling-assistant
 <261620128+schickling-assistant@users.noreply.github.com>
Date: Fri, 31 Jul 2026 13:10:30 +0200
Subject: [PATCH 1/3] feat: patch session metadata atomically

---
 CHANGELOG.md                  |  16 +++
 README.md                     |  15 +++
 completions/pty.bash          |   5 +-
 completions/pty.fish          |   3 +
 completions/pty.zsh           |   6 +
 docs/client.md                |  34 +++++
 docs/disk-layout.md           |   3 +-
 src/cli.ts                    |  81 ++++++++++++
 src/client-api.ts             |   7 +-
 src/completions.ts            |   6 +
 src/events.ts                 |  18 ++-
 src/sessions.ts               | 242 ++++++++++++++++++++++++++--------
 tests/help.test.ts            |   2 +-
 tests/metadata-events.test.ts | 167 ++++++++++++++++++++++-
 14 files changed, 539 insertions(+), 66 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf93201..b88424e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### Atomic exact-id metadata patching
+
+- `pty metadata patch --id <stable-id>` reads one merge-style JSON object from
+  stdin and atomically updates `displayName` and tags under one metadata lock.
+  It never falls back to display-name lookup, preserves unrelated tags, returns
+  `{ changed, metadata }`, and suppresses no-op writes and events.
+- `patchMetadataById(id, patch)` exposes the same exact-id operation from
+  `@compoundingtech/pty/client`. Existing rename/tag APIs share the merge engine
+  while retaining their documented specialized events for compatibility.
+
+### Storage format
+
+Effective atomic patches append one `metadata_change` event whose `previous`
+and `value` objects contain only changed `displayName` and tag keys. No-op
+patches append no event.
+
 ### Non-unique display names with unambiguous session resolution
 
 - Display names are presentation metadata and no longer need to be unique.
diff --git a/README.md b/README.md
index 68570fb..45f758d 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,7 @@ pty rename my-label                       # inside a session: add/change its dis
 pty rename <ref> my-label                 # outside: set displayName on <ref>
 pty rename --show <ref>                   # show current displayName
 pty rename --clear [ref]                  # remove displayName
+pty metadata patch --id myserver < patch.json # atomically patch displayName/tags by exact id
 
 pty list                                  # show active sessions (tags shown by default)
 pty list --tags                           # include internal bookkeeping tags (ptyfile*, strategy, etc.)
@@ -125,6 +126,20 @@ exact stable id first, then a display name only when that label has one match.
 Ambiguous display names fail without acting and print the candidate stable ids.
 Use stable ids in scripts and automation.
 
+For automation that must update presentation metadata without alias fallback,
+`pty metadata patch --id <stable-id>` reads one merge-style JSON object from
+stdin and returns `{ changed, metadata }` as JSON:
+
+```sh
+printf '%s' '{"displayName":"Worker","tags":{"role":"worker","old":null}}' \
+  | pty metadata patch --id a1b2c3d4
+```
+
+`displayName` and individual tag values use strings to set and `null` to clear;
+omitted fields and tag keys remain unchanged. The operation holds the session's
+metadata lock across one read/merge/atomic-write cycle. It fails if the exact id
+is absent, even when a display name has the same text.
+
 ### Remote over fabric
 
 `pty list --remote <peer>` lists another machine's sessions over [fabric](https://github.com/compoundingtech/fabric), which hands consumers a plain local Unix socket — pty never touches iroh. The remote machine serves a small control protocol that fabric exposes under the `pty-remote` ALPN. The recommended form is **on-demand**: fabric spawns the handler per dial, pipes the connection to its stdin/stdout, and owns persistence + roaming (no persistent pty daemon):
diff --git a/completions/pty.bash b/completions/pty.bash
index d9c17d8..4bfe51d 100644
--- a/completions/pty.bash
+++ b/completions/pty.bash
@@ -5,7 +5,7 @@ _pty() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
-  commands="run attach a exec peek send events list ls stats restart kill rm remove gc tag tag-multi emit rename up down test remote-serve"
+  commands="run attach a exec peek send events list ls stats restart kill rm remove gc tag tag-multi emit rename metadata up down test remote-serve"
 
   if [[ ${COMP_CWORD} -eq 1 ]]; then
     if [[ "${cur}" == -* ]]; then
@@ -119,6 +119,9 @@ _pty() {
         COMPREPLY=($(compgen -W "${names}" -- "${cur}"))
       fi
       ;;
+    metadata)
+      COMPREPLY=($(compgen -W "--id" -- "${cur}"))
+      ;;
     up)
       COMPREPLY=($(compgen -o dirnames -- "${cur}"))
       ;;
diff --git a/completions/pty.fish b/completions/pty.fish
index 78c6c27..f4570d3 100644
--- a/completions/pty.fish
+++ b/completions/pty.fish
@@ -60,6 +60,7 @@ complete -c pty -n __pty_needs_command -a tag -d 'Read / write tags on one sessi
 complete -c pty -n __pty_needs_command -a tag-multi -d 'Bulk tag ops across sessions'
 complete -c pty -n __pty_needs_command -a emit -d 'Publish a user.* event'
 complete -c pty -n __pty_needs_command -a rename -d 'Set / show / clear displayName'
+complete -c pty -n __pty_needs_command -a metadata -d 'Atomically patch presentation metadata by stable id'
 complete -c pty -n __pty_needs_command -a up -d 'Start sessions from pty.toml'
 complete -c pty -n __pty_needs_command -a down -d 'Stop sessions from pty.toml'
 complete -c pty -n __pty_needs_command -a test -d 'Run the pty test suite (vitest)'
@@ -135,6 +136,8 @@ complete -c pty -n '__pty_using_command emit' -a '(__pty_sessions)' -d 'Session'
 complete -c pty -n '__pty_using_command rename' -l show -d 'Print current displayName'
 complete -c pty -n '__pty_using_command rename' -l clear -d 'Remove displayName'
 complete -c pty -n '__pty_using_command rename' -a '(__pty_sessions)' -d 'Session'
+complete -c pty -n '__pty_using_command metadata' -l id -d 'Exact stable session id'
+complete -c pty -n '__pty_using_command metadata' -x -a 'patch' -d 'Value'
 complete -c pty -n '__pty_using_command up' -F
 complete -c pty -n '__pty_using_command down' -F
 complete -c pty -n '__pty_using_command test' -l t -d 'Run matching tests'
diff --git a/completions/pty.zsh b/completions/pty.zsh
index 84cb4ac..93755e5 100644
--- a/completions/pty.zsh
+++ b/completions/pty.zsh
@@ -33,6 +33,7 @@ _pty() {
     'tag-multi:Bulk tag ops across sessions'
     'emit:Publish a user.* event'
     'rename:Set / show / clear displayName'
+    'metadata:Atomically patch presentation metadata by stable id'
     'up:Start sessions from pty.toml'
     'down:Stop sessions from pty.toml'
     'test:Run the pty test suite (vitest)'
@@ -171,6 +172,11 @@ _pty() {
             '--clear[Remove displayName]' \
             '1:session:_pty_sessions'
           ;;
+        metadata)
+          _arguments \
+            '--id[Exact stable session id]' \
+            '1:mode:(patch)'
+          ;;
         up)
           _arguments \
             '1:directory:_directories'
diff --git a/docs/client.md b/docs/client.md
index 461a502..88a5cfb 100644
--- a/docs/client.md
+++ b/docs/client.md
@@ -27,6 +27,36 @@ matches. Resolve once, then pass `session.name` to socket-oriented APIs.
 
 Throws if the name is invalid. Names must match `[a-zA-Z0-9._-]` and be at most 255 characters.
 
+### `patchMetadataById(id: string, patch: MetadataPatch): Promise<MetadataPatchResult>`
+
+Atomically merge presentation metadata for one exact stable id. This API never
+falls back to a matching display name. It holds the session metadata lock across
+one read, merge, validation, and atomic write; unrelated tags are preserved and
+a no-op returns `changed: false` without writing or emitting an event.
+
+```typescript
+const result = await patchMetadataById("a1b2c3d4", {
+  displayName: "Worker",
+  tags: { role: "worker", temporary: null },
+});
+
+interface MetadataPatch {
+  displayName?: string | null;
+  tags?: Record<string, string | null>;
+}
+
+interface MetadataPatchResult {
+  changed: boolean;
+  metadata: SessionMetadata;
+}
+```
+
+Strings set values, `null` clears them, and omitted fields or tag keys remain
+unchanged. A successful change emits one `metadata_change` event containing
+only effective changes as `previous` and `value` snapshots. The existing
+`setDisplayName` and `updateTags` APIs retain their specialized event types for
+compatibility.
+
 ### `getSessionDir(): string`
 
 Returns the session directory path — `$PTY_ROOT` if set (the legacy `$PTY_SESSION_DIR` name is still honored), otherwise `~/.local/state/pty`.
@@ -382,6 +412,10 @@ Each extends `EventBase { session: string; type: EventType; ts: string }`.
 `NotificationEvent` adds `title?`, `body?`, `source?: "osc9" | "osc99" | "osc777"`.
 `TitleChangeEvent` adds `value: string`.
 
+`MetadataChangeEvent` has type `"metadata_change"` and carries `previous` and
+`value` objects. Only the changed `displayName` field and changed tag keys are
+present; `null` represents an absent or cleared value.
+
 ## Keys (also available via `@compoundingtech/pty/keys`)
 
 These functions are also available as a standalone browser-safe import via `@compoundingtech/pty/keys` (zero dependencies).
diff --git a/docs/disk-layout.md b/docs/disk-layout.md
index 5d9f838..cb5d2a9 100644
--- a/docs/disk-layout.md
+++ b/docs/disk-layout.md
@@ -94,6 +94,7 @@ Envelope: `{ session: string; type: string; ts: string; ...payload }`. Event typ
 | `session_flapping` | `counter, limit, window` — (`pty gc` flipped a permanent session to `strategy.status=flapping` after N consecutive fast-fail respawns; subsequent ticks skip it) |
 | `display_name_change` | `previous: string\|null, value: string\|null` |
 | `tags_change` | `previous, value` (full snapshots) |
+| `metadata_change` | `previous, value` containing only changed `displayName` and tag keys; absent tag values are `null` |
 | `user.<name>` | `data?, text?` — free-form, via `pty emit` |
 
 A single line ≤ `PIPE_BUF` (~4 KB) is atomic per POSIX `O_APPEND`. Built-ins are well under. Keep large `user.*` payloads out of the event stream.
@@ -104,4 +105,4 @@ A single line ≤ `PIPE_BUF` (~4 KB) is atomic per POSIX `O_APPEND`. Built-ins a
 jq -r '.tags["role"] // empty' "$PTY_ROOT/myserver.json"
 ```
 
-For live updates, tail `<name>.events.jsonl` via `inotify` / `kqueue`. Subscribe instead of polling — `tags_change` / `display_name_change` / `session_*` fire on every mutation.
+For live updates, tail `<name>.events.jsonl` via `inotify` / `kqueue`. Subscribe instead of polling — `metadata_change` / `tags_change` / `display_name_change` / `session_*` fire on every mutation.
diff --git a/src/cli.ts b/src/cli.ts
index 2a9ff72..2702cf6 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -25,6 +25,7 @@ import {
   releaseLock,
   updateTags,
   setDisplayName,
+  patchMetadataById,
   allSessionNames,
   readMetadata,
   readSessionPid,
@@ -356,6 +357,20 @@ Examples:
   pty rename webapp "Web Frontend"
   pty rename --show webapp`,
 
+  metadata: `Usage: pty metadata patch --id <stable-id>
+
+Atomically merge displayName and tags for one exact stable session id. Reads
+one JSON object from stdin; it never resolves display-name aliases.
+
+Patch fields:
+  displayName   string to set, null to clear, omitted to preserve
+  tags          object of string values to set and null values to remove
+
+Examples:
+  pty metadata patch --id a1b2c3d4 < patch.json
+  printf '%s' '{"displayName":"Worker","tags":{"role":"worker"}}' | pty metadata patch --id a1b2c3d4
+  printf '%s' '{"displayName":null,"tags":{"temporary":null}}' | pty metadata patch --id a1b2c3d4`,
+
   up: `Usage: pty up [<dir>] [<name>...]
 
 Start sessions declared in a pty.toml. With no args, reads ./pty.toml and starts all.
@@ -452,6 +467,7 @@ Observe:
   pty remote-serve --socket <path>        Serve remote access as a listening daemon (being retired)
 
 Modify:
+  pty metadata patch --id <id>            Atomically merge displayName/tags from JSON stdin
   pty rename <label>                      Inside a session: set its displayName
   pty rename <ref> <label>                Outside: set displayName on <ref>
   pty rename --show <ref>                 Print the current displayName
@@ -1450,6 +1466,11 @@ async function main(): Promise<void> {
       break;
     }
 
+    case "metadata": {
+      await cmdMetadata(args.slice(1));
+      break;
+    }
+
     case "rm":
     case "remove": {
       if (args.length < 2) {
@@ -2464,6 +2485,66 @@ function renameUsage(): void {
   console.error(COMMAND_HELP.rename);
 }
 
+async function cmdMetadata(rawArgs: string[]): Promise<void> {
+  if (rawArgs[0] === "patch" && (rawArgs[1] === "-h" || rawArgs[1] === "--help")) {
+    printCommandHelp("metadata");
+    return;
+  }
+  if (rawArgs[0] !== "patch") {
+    console.error('pty metadata: expected subcommand "patch".');
+    console.error("  Usage: pty metadata patch --id <stable-id>");
+    process.exit(1);
+  }
+
+  let id: string | null = null;
+  for (let i = 1; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--id") {
+      const value = rawArgs[++i];
+      if (!value) {
+        console.error("pty metadata patch: --id requires a stable session id.");
+        process.exit(1);
+      }
+      if (id !== null) {
+        console.error("pty metadata patch: --id may only be provided once.");
+        process.exit(1);
+      }
+      id = value;
+    } else {
+      console.error(`pty metadata patch: unexpected argument "${arg}".`);
+      console.error("  Usage: pty metadata patch --id <stable-id>");
+      process.exit(1);
+    }
+  }
+  if (id === null) {
+    console.error("pty metadata patch: missing required --id <stable-id>.");
+    process.exit(1);
+  }
+
+  const input = fs.readFileSync(0, "utf-8").trim();
+  if (input.length === 0) {
+    console.error("pty metadata patch: expected one JSON patch object on stdin.");
+    console.error('  Example: printf \'%s\' \'{"displayName":"Worker"}\' | pty metadata patch --id a1b2c3d4');
+    process.exit(1);
+  }
+
+  let patch: unknown;
+  try {
+    patch = JSON.parse(input);
+  } catch (e) {
+    console.error(`pty metadata patch: invalid JSON on stdin: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  try {
+    const result = await patchMetadataById(id, patch as any);
+    console.log(JSON.stringify(result));
+  } catch (e) {
+    console.error(`pty metadata patch: ${(e as Error).message}`);
+    process.exit(1);
+  }
+}
+
 async function cmdRename(rawArgs: string[]): Promise<void> {
   const insideSession = !!process.env.PTY_SESSION;
 
diff --git a/src/client-api.ts b/src/client-api.ts
index 5bcefa4..b20118a 100644
--- a/src/client-api.ts
+++ b/src/client-api.ts
@@ -4,14 +4,15 @@
 // Session management
 export {
   listSessions, getSession, gc, pruneOrphanLayoutTags, isGone,
-  validateName, updateTags, setDisplayName,
+  validateName, updateTags, setDisplayName, patchMetadataById,
   getSessionDir, getSocketPath,
   cleanupSocket, cleanupAll,
   // Exposed for the same reason as `isReservedTagKey`: downstream tools
   // (relay, layout, supervisors) need to answer "is this session exempt
   // from reaping?" without re-deriving which tag values count as set.
   KEEP_TAG, isKeepRequested, shouldReapAtExit,
-  type SessionInfo, type SessionMetadata, type PrunedTagResult, type GcResult,
+  type SessionInfo, type SessionMetadata, type MetadataPatch, type MetadataPatchResult,
+  type PrunedTagResult, type GcResult,
 } from "./sessions.ts";
 
 // Session creation
@@ -42,7 +43,7 @@ export {
   type SessionStartEvent, type SessionExitEvent, type SessionExecEvent,
   type SessionRespawnEvent,
   type UserEvent,
-  type DisplayNameChangeEvent, type TagsChangeEvent,
+  type DisplayNameChangeEvent, type TagsChangeEvent, type MetadataChangeEvent,
   type FollowerOptions,
 } from "./events.ts";
 
diff --git a/src/completions.ts b/src/completions.ts
index 528083e..89f7b81 100644
--- a/src/completions.ts
+++ b/src/completions.ts
@@ -220,6 +220,12 @@ const COMMANDS: readonly CommandSpec[] = [
       { name: "clear", desc: "Remove displayName" },
     ],
   },
+  {
+    name: "metadata",
+    desc: "Atomically patch presentation metadata by stable id",
+    flags: [{ name: "id", desc: "Exact stable session id" }],
+    positionalValues: ["patch"],
+  },
   {
     name: "up",
     desc: "Start sessions from pty.toml",
diff --git a/src/events.ts b/src/events.ts
index 4e9e5bd..9551fbc 100644
--- a/src/events.ts
+++ b/src/events.ts
@@ -158,6 +158,19 @@ export interface TagsChangeEvent extends EventBase {
   value: Record<string, string>;
 }
 
+export interface MetadataChangeEvent extends EventBase {
+  type: "metadata_change";
+  /** Only fields and tag keys that effectively changed are present. */
+  previous: {
+    displayName?: string | null;
+    tags?: Record<string, string | null>;
+  };
+  value: {
+    displayName?: string | null;
+    tags?: Record<string, string | null>;
+  };
+}
+
 export type EventRecord =
   | BellEvent
   | TitleChangeEvent
@@ -172,7 +185,8 @@ export type EventRecord =
   | SessionFlappingEvent
   | UserEvent
   | DisplayNameChangeEvent
-  | TagsChangeEvent;
+  | TagsChangeEvent
+  | MetadataChangeEvent;
 
 /** Type guard: narrows an EventRecord to a UserEvent. */
 export function isUserEvent(e: EventRecord): e is UserEvent {
@@ -527,6 +541,8 @@ export function formatEvent(event: EventRecord): string {
         Object.keys(t).length === 0 ? "{}" : Object.entries(t).map(([k, v]) => `${k}=${v}`).join(" ");
       return `${prefix} tags -> ${fmt(event.value)} (was ${fmt(event.previous)})`;
     }
+    case "metadata_change":
+      return `${prefix} metadata -> ${JSON.stringify(event.value)} (was ${JSON.stringify(event.previous)})`;
     default: {
       // user.* events + anything else unknown-at-compile-time.
       const e = event as EventBase & { data?: unknown; text?: string };
diff --git a/src/sessions.ts b/src/sessions.ts
index 987648a..64a4bd8 100644
--- a/src/sessions.ts
+++ b/src/sessions.ts
@@ -236,32 +236,192 @@ export function writeMetadata(name: string, metadata: SessionMetadata): void {
   atomicWriteFileSync(getMetadataPath(name), JSON.stringify(metadata, null, 2));
 }
 
+export interface MetadataPatch {
+  displayName?: string | null;
+  tags?: Record<string, string | null>;
+}
+
+export interface MetadataPatchResult {
+  changed: boolean;
+  metadata: SessionMetadata;
+}
+
+type MetadataChangeSnapshot = {
+  displayName?: string | null;
+  tags?: Record<string, string | null>;
+};
+
+type MetadataPatchEvent = "metadata_change" | "display_name_change" | "tags_change";
+
+function validateMetadataPatch(patch: unknown): asserts patch is MetadataPatch {
+  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) {
+    throw new Error("Metadata patch must be a JSON object.");
+  }
+  for (const key of Object.keys(patch)) {
+    if (key !== "displayName" && key !== "tags") {
+      throw new Error(`Metadata patch has unknown field "${key}". Allowed fields: displayName, tags.`);
+    }
+  }
+  const candidate = patch as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(candidate, "displayName")) {
+    if (candidate.displayName !== null && typeof candidate.displayName !== "string") {
+      throw new Error("Metadata patch displayName must be a string or null.");
+    }
+    if (typeof candidate.displayName === "string") {
+      try {
+        validateDisplayName(candidate.displayName);
+      } catch (e) {
+        throw new Error(`Invalid displayName: ${(e as Error).message}`);
+      }
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(candidate, "tags")) {
+    const tags = candidate.tags;
+    if (tags === null || typeof tags !== "object" || Array.isArray(tags)) {
+      throw new Error("Metadata patch tags must be a JSON object.");
+    }
+    for (const [key, value] of Object.entries(tags as Record<string, unknown>)) {
+      if (key.length === 0) throw new Error("Metadata patch tag keys must be non-empty.");
+      if (value !== null && typeof value !== "string") {
+        throw new Error(`Metadata patch tag values must be strings or null (invalid key: "${key}").`);
+      }
+    }
+  }
+}
+
+function setRecordValue(record: Record<string, string>, key: string, value: string): void {
+  Object.defineProperty(record, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
+function applyMetadataPatchById(
+  id: string,
+  patch: MetadataPatch,
+  eventType: MetadataPatchEvent,
+): MetadataPatchResult {
+  validateMetadataPatch(patch);
+  if (!acquireLock(id)) {
+    throw new Error(`Session id "${id}" metadata is busy. Retry the operation.`);
+  }
+
+  try {
+    const metadata = readMetadata(id);
+    if (!metadata) throw new Error(`Session id "${id}" not found.`);
+
+    const previousTags = Object.fromEntries(Object.entries(metadata.tags ?? {}));
+    const nextTags = Object.fromEntries(Object.entries(previousTags));
+    const previous: MetadataChangeSnapshot = {};
+    const value: MetadataChangeSnapshot = {};
+
+    if (Object.prototype.hasOwnProperty.call(patch, "displayName")) {
+      const before = metadata.displayName ?? null;
+      const after = patch.displayName ?? null;
+      if (before !== after) {
+        previous.displayName = before;
+        value.displayName = after;
+        if (after === null) delete metadata.displayName;
+        else metadata.displayName = after;
+      }
+    }
+
+    if (patch.tags !== undefined) {
+      const changedTagKeys: string[] = [];
+      for (const [key, requested] of Object.entries(patch.tags)) {
+        const before = Object.prototype.hasOwnProperty.call(previousTags, key)
+          ? previousTags[key]
+          : null;
+        const after = requested ?? null;
+        if (before === after) continue;
+        changedTagKeys.push(key);
+        if (after === null) delete nextTags[key];
+        else setRecordValue(nextTags, key, after);
+      }
+      if (changedTagKeys.length > 0) {
+        previous.tags = {};
+        value.tags = {};
+        for (const key of changedTagKeys.sort()) {
+          const before = Object.prototype.hasOwnProperty.call(previousTags, key)
+            ? previousTags[key]
+            : null;
+          const after = Object.prototype.hasOwnProperty.call(nextTags, key)
+            ? nextTags[key]
+            : null;
+          Object.defineProperty(previous.tags, key, { value: before, enumerable: true });
+          Object.defineProperty(value.tags, key, { value: after, enumerable: true });
+        }
+        if (Object.keys(nextTags).length === 0) delete metadata.tags;
+        else metadata.tags = nextTags;
+      }
+    }
+
+    const changed = Object.keys(previous).length > 0;
+    if (!changed) return { changed: false, metadata };
+
+    if (metadata.displayName !== undefined) validateDisplayName(metadata.displayName);
+    for (const [key, tagValue] of Object.entries(metadata.tags ?? {})) {
+      if (key.length === 0) throw new Error("Resulting metadata contains an empty tag key.");
+      if (typeof tagValue !== "string") {
+        throw new Error(`Resulting metadata tag "${key}" is not a string.`);
+      }
+    }
+
+    writeMetadata(id, metadata);
+    if (eventType === "metadata_change") {
+      appendEventSync(id, {
+        session: id,
+        type: "metadata_change",
+        ts: new Date().toISOString(),
+        previous,
+        value,
+      });
+    } else if (eventType === "display_name_change") {
+      appendEventSync(id, {
+        session: id,
+        type: "display_name_change",
+        ts: new Date().toISOString(),
+        previous: previous.displayName ?? null,
+        value: value.displayName ?? null,
+      });
+    } else {
+      appendEventSync(id, {
+        session: id,
+        type: "tags_change",
+        ts: new Date().toISOString(),
+        previous: previousTags,
+        value: nextTags,
+      });
+    }
+    return { changed: true, metadata };
+  } finally {
+    releaseLock(id);
+  }
+}
+
+/** Atomically merge presentation metadata for one exact stable session id. */
+export async function patchMetadataById(
+  id: string,
+  patch: MetadataPatch,
+): Promise<MetadataPatchResult> {
+  validateMetadataPatch(patch);
+  const session = await getSessionByName(id);
+  if (!session) throw new Error(`Session id "${id}" not found.`);
+  return applyMetadataPatchById(id, patch, "metadata_change");
+}
+
 /** Set or clear the displayName on an existing session. Atomic read-modify-write.
  *  Pass `null` to remove the alias. Throws if `name` doesn't exist. Emits a
  *  `display_name_change` event when (and only when) the value actually
  *  changed — no-op renames don't ping downstream watchers. */
 export function setDisplayName(name: string, displayName: string | null): void {
-  const metadata = readMetadata(name);
-  if (!metadata) {
-    throw new Error(`Session "${name}" not found.`);
-  }
-  const previous = metadata.displayName ?? null;
-  const next = displayName === null || displayName === "" ? null : displayName;
-  if (previous === next) return; // no-op write + no-op event
-
-  if (next === null) {
-    delete metadata.displayName;
-  } else {
-    metadata.displayName = next;
-  }
-  writeMetadata(name, metadata);
-  appendEventSync(name, {
-    session: name,
-    type: "display_name_change",
-    ts: new Date().toISOString(),
-    previous,
-    value: next,
-  });
+  applyMetadataPatchById(
+    name,
+    { displayName: displayName === "" ? null : displayName },
+    "display_name_change",
+  );
 }
 
 /** Update tags on an existing session. Performs an atomic read-modify-write.
@@ -273,43 +433,9 @@ export function updateTags(
   updates: Record<string, string>,
   removals: string[] = [],
 ): void {
-  const metadata = readMetadata(name);
-  if (!metadata) {
-    throw new Error(`Session "${name}" not found.`);
-  }
-  const previous = { ...(metadata.tags ?? {}) };
-  const tags = { ...previous };
-  for (const [k, v] of Object.entries(updates)) {
-    tags[k] = v;
-  }
-  for (const k of removals) {
-    delete tags[k];
-  }
-  if (tagsEqual(previous, tags)) return; // no-op write + no-op event
-
-  if (Object.keys(tags).length > 0) {
-    metadata.tags = tags;
-  } else {
-    delete metadata.tags;
-  }
-  writeMetadata(name, metadata);
-  appendEventSync(name, {
-    session: name,
-    type: "tags_change",
-    ts: new Date().toISOString(),
-    previous,
-    value: tags,
-  });
-}
-
-function tagsEqual(a: Record<string, string>, b: Record<string, string>): boolean {
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  if (aKeys.length !== bKeys.length) return false;
-  for (const k of aKeys) {
-    if (!Object.prototype.hasOwnProperty.call(b, k) || a[k] !== b[k]) return false;
-  }
-  return true;
+  const tags: Record<string, string | null> = { ...updates };
+  for (const key of removals) tags[key] = null;
+  applyMetadataPatchById(name, { tags }, "tags_change");
 }
 
 export function readMetadata(name: string): SessionMetadata | null {
diff --git a/tests/help.test.ts b/tests/help.test.ts
index 698550e..bed950e 100644
--- a/tests/help.test.ts
+++ b/tests/help.test.ts
@@ -12,7 +12,7 @@ const cliSource = fs.readFileSync(path.join(__dirname, "..", "src", "cli.ts"), "
 // Canonical subcommands that must each ship focused `--help`.
 const COMMANDS = [
   "run", "attach", "exec", "peek", "send", "events", "list", "stats",
-  "restart", "kill", "rm", "gc", "tag", "tag-multi", "emit", "rename",
+  "restart", "kill", "rm", "gc", "tag", "tag-multi", "emit", "rename", "metadata",
   "up", "down", "test", "remote-serve",
 ];
 // Aliases that must resolve to the same help.
diff --git a/tests/metadata-events.test.ts b/tests/metadata-events.test.ts
index 40f4d39..c0df4e8 100644
--- a/tests/metadata-events.test.ts
+++ b/tests/metadata-events.test.ts
@@ -11,7 +11,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import {
-  setDisplayName, updateTags, readMetadata,
+  patchMetadataById, setDisplayName, updateTags, readMetadata,
 } from "../src/sessions.ts";
 import { EventFollower, formatEvent, type EventRecord } from "../src/events.ts";
 
@@ -78,6 +78,15 @@ function runCli(sessionDir: string, env: Record<string, string>, ...args: string
   });
 }
 
+function runCliWithInput(sessionDir: string, input: string, ...args: string[]) {
+  return spawnSync(nodeBin, [cliPath, ...args], {
+    env: { ...process.env, PTY_SESSION_DIR: sessionDir },
+    input,
+    encoding: "utf-8",
+    timeout: 10_000,
+  });
+}
+
 afterEach(async () => {
   await terminateAndWait(bgPids);
   bgPids = [];
@@ -96,6 +105,149 @@ function readEvents(dir: string, name: string): any[] {
   } catch { return []; }
 }
 
+describe("patchMetadataById", () => {
+  it("atomically changes displayName and tags while preserving unrelated tags", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    updateTags(name, { keep: "yes", replace: "old", remove: "old" });
+
+    const result = await patchMetadataById(name, {
+      displayName: "Worker",
+      tags: { replace: "new", remove: null, added: "yes" },
+    });
+
+    expect(result.changed).toBe(true);
+    expect(result.metadata.displayName).toBe("Worker");
+    expect(result.metadata.tags).toEqual({ keep: "yes", replace: "new", added: "yes" });
+    const changes = readEvents(dir, name).filter((event) => event.type === "metadata_change");
+    expect(changes).toHaveLength(1);
+    expect(changes[0].previous).toEqual({
+      displayName: null,
+      tags: { replace: "old", remove: "old", added: null },
+    });
+    expect(changes[0].value).toEqual({
+      displayName: "Worker",
+      tags: { replace: "new", remove: null, added: "yes" },
+    });
+  }, 15000);
+
+  it("supports clear operations and emits one coherent event", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    await patchMetadataById(name, { displayName: "Before", tags: { remove: "yes", keep: "yes" } });
+
+    const result = await patchMetadataById(name, {
+      displayName: null,
+      tags: { remove: null },
+    });
+
+    expect(result.metadata.displayName).toBeUndefined();
+    expect(result.metadata.tags).toEqual({ keep: "yes" });
+    const changes = readEvents(dir, name).filter((event) => event.type === "metadata_change");
+    expect(changes).toHaveLength(2);
+    expect(changes[1].previous).toEqual({ displayName: "Before", tags: { remove: "yes" } });
+    expect(changes[1].value).toEqual({ displayName: null, tags: { remove: null } });
+  }, 15000);
+
+  it("suppresses both the write result and event for a no-op", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    await patchMetadataById(name, { displayName: "Stable", tags: { role: "worker" } });
+    const before = readEvents(dir, name).filter((event) => event.type === "metadata_change").length;
+
+    const result = await patchMetadataById(name, {
+      displayName: "Stable",
+      tags: { role: "worker", absent: null },
+    });
+
+    expect(result.changed).toBe(false);
+    expect(readEvents(dir, name).filter((event) => event.type === "metadata_change")).toHaveLength(before);
+  }, 15000);
+
+  it("never falls back from a missing stable id to a matching displayName", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    setDisplayName(name, "missing-id");
+
+    await expect(patchMetadataById("missing-id", { tags: { wrong: "target" } }))
+      .rejects.toThrow('Session id "missing-id" not found');
+    expect(readMetadata(name)?.tags?.wrong).toBeUndefined();
+  }, 15000);
+
+  it.each([
+    [{ displayName: "bad/name" }, /Invalid displayName/],
+    [{ tags: { "": "value" } }, /tag keys must be non-empty/],
+    [{ tags: { role: 1 } }, /tag values must be strings or null/],
+    [{ unknown: true }, /unknown field "unknown"/],
+  ])("rejects an invalid patch without writing metadata", async (patch, message) => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    const before = readMetadata(name);
+
+    await expect(patchMetadataById(name, patch as any)).rejects.toThrow(message);
+    expect(readMetadata(name)).toEqual(before);
+    expect(readEvents(dir, name).filter((event) => event.type === "metadata_change")).toHaveLength(0);
+  }, 15000);
+
+  it("exposes the exact-id atomic operation through JSON stdin/stdout", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+
+    const result = runCliWithInput(
+      dir,
+      JSON.stringify({ displayName: "CLI Worker", tags: { role: "worker" } }),
+      "metadata", "patch", "--id", name,
+    );
+
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      changed: true,
+      metadata: { displayName: "CLI Worker", tags: { role: "worker" } },
+    });
+    expect(readEvents(dir, name).filter((event) => event.type === "metadata_change")).toHaveLength(1);
+  }, 15000);
+
+  it("CLI exact-id lookup refuses a same-string displayName alias", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    setDisplayName(name, "missing-id");
+
+    const result = runCliWithInput(
+      dir,
+      JSON.stringify({ tags: { wrong: "target" } }),
+      "metadata", "patch", "--id", "missing-id",
+    );
+
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('Session id "missing-id" not found');
+    expect(readMetadata(name)?.tags?.wrong).toBeUndefined();
+  }, 15000);
+
+  it.each([
+    [[], "{}", /missing required --id/],
+    [["--id", "target"], "not-json", /invalid JSON on stdin/],
+    [["--id", "target"], "[]", /Metadata patch must be a JSON object/],
+  ])("CLI reports actionable input errors", (args, input, message) => {
+    const dir = makeSessionDir();
+    const result = runCliWithInput(dir, input, "metadata", "patch", ...args);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toMatch(message);
+  });
+});
+
 describe("setDisplayName — display_name_change event", () => {
   it("emits on a real change, with previous + value populated", async () => {
     const dir = makeSessionDir();
@@ -356,4 +508,17 @@ describe("formatEvent for new metadata events", () => {
     });
     expect(line).toContain("{}");
   });
+
+  it("formats metadata_change with coherent previous/value snapshots", () => {
+    const line = formatEvent({
+      session: "test",
+      type: "metadata_change",
+      ts: "2026-04-23T10:15:03.000Z",
+      previous: { displayName: null, tags: { role: null } },
+      value: { displayName: "Worker", tags: { role: "worker" } },
+    });
+    expect(line).toContain("metadata ->");
+    expect(line).toContain('"Worker"');
+    expect(line).toContain('"worker"');
+  });
 });

From 706e4f5e4cd88fe24ce5b8afb7dbd507bd3e215c Mon Sep 17 00:00:00 2001
From: schickling-assistant
 <261620128+schickling-assistant@users.noreply.github.com>
Date: Fri, 31 Jul 2026 16:48:19 +0200
Subject: [PATCH 2/3] feat: make session metadata lifecycle-safe

---
 CHANGELOG.md                  |  12 +-
 README.md                     |   2 +-
 completions/pty.fish          |   2 +-
 completions/pty.zsh           |   2 +-
 docs/client.md                |   6 +-
 docs/disk-layout.md           |   8 +-
 src/cli.ts                    |  95 +++++++---
 src/completions.ts            |   2 +-
 src/events.ts                 | 110 ++++++++----
 src/server.ts                 |  87 +++++----
 src/sessions.ts               | 327 ++++++++++++++++++++++------------
 src/spawn.ts                  |  55 +++++-
 src/tui/interactive.ts        |  32 ++--
 tests/atomic-writes.test.ts   | 142 ++++++++++++++-
 tests/display-name.test.ts    |  27 +++
 tests/gc-parent-child.test.ts |  23 +++
 tests/metadata-events.test.ts | 177 +++++++++++++++++-
 tests/spawn-options.test.ts   | 130 +++++++++++++-
 18 files changed, 986 insertions(+), 253 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1c040d..134f942 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,12 +34,22 @@
 - `patchMetadataById(id, patch)` exposes the same exact-id operation from
   `@compoundingtech/pty/client`. Existing rename/tag APIs share the merge engine
   while retaining their documented specialized events for compatibility.
+- Metadata publication acquires the event lock before the metadata lock, so a
+  busy event log fails before either file changes. Event appends and retention
+  rewrites are serialized without a per-record byte-size assumption.
+- The current display-name contract supersedes the permissive limits described
+  in earlier release notes: values must be nonempty, already trimmed,
+  single-line, free of Unicode control characters, and at most 160 Unicode
+  scalar values. Slash and backslash remain valid metadata characters.
 
 ### Storage format
 
 Effective atomic patches append one `metadata_change` event whose `previous`
 and `value` objects contain only changed `displayName` and tag keys. No-op
-patches append no event.
+patches append no event. Lock contention cannot publish only one side of an
+effective patch. Metadata remains the authoritative state: a process crash or
+underlying I/O failure between its write and event append can omit the
+notification because pty does not journal a cross-file transaction.
 
 ### Non-unique display names with unambiguous session resolution
 
diff --git a/README.md b/README.md
index 93292f9..7a50bdd 100644
--- a/README.md
+++ b/README.md
@@ -286,7 +286,7 @@ display_name = "My Web Server"   # override the default `<prefix>-<sessionKey>`
 cwd = "packages/web"             # working directory (default: the manifest's dir)
 ```
 
-`id` is validated like a `pty run --id` value (charset, sock-path length, uniqueness); omitted → pty generates a short random id at spawn time. `display_name` is permissive (≤ 500 chars, any printable text); omitted → defaults to `<prefix>-<sessionKey>` (or just `<sessionKey>` if no prefix). The two fields decouple the human label from the kernel-constrained filename — long prefixes that would have blown past `sockaddr_un.sun_path` (~104 bytes) now work because the actual sock filename is just the short id.
+`id` is validated like a `pty run --id` value (charset, sock-path length, uniqueness); omitted → pty generates a short random id at spawn time. `display_name` must be nonempty, already trimmed, single-line, free of Unicode control characters, and at most 160 Unicode scalar values; `/` and `\` are allowed because the value is metadata, not a path. Omitted → defaults to `<prefix>-<sessionKey>` (or just `<sessionKey>` if no prefix). The two fields decouple the human label from the kernel-constrained filename — long prefixes that would have blown past `sockaddr_un.sun_path` (~104 bytes) now work because the actual sock filename is just the short id.
 
 `cwd` sets the session's working directory. An absolute path is used as-is; a relative path resolves against the manifest's directory. Omitted → the session runs in the manifest's directory (the default). This decouples where a session runs from where its `pty.toml` lives — so a manifest kept in a subdirectory (e.g. `.convoy/pty.toml`, to keep a repo root pristine) can still run its sessions in the repo root with `cwd = ".."`. The declared `cwd` is honored on the initial `pty up` and preserved across manual and `strategy=permanent` respawns.
 
diff --git a/completions/pty.fish b/completions/pty.fish
index ca3fdae..5bd8a67 100644
--- a/completions/pty.fish
+++ b/completions/pty.fish
@@ -69,7 +69,7 @@ complete -c pty -n '__pty_using_command run' -l detach -s d -d 'Create in the ba
 complete -c pty -n '__pty_using_command run' -l attach -s a -d 'Create OR attach if id already exists'
 complete -c pty -n '__pty_using_command run' -l ephemeral -s e -d 'Ephemeral: auto-remove metadata on clean exit'
 complete -c pty -n '__pty_using_command run' -l id -d 'Pin on-disk id (charset-validated)'
-complete -c pty -n '__pty_using_command run' -l name -d 'Display label (any printable, ≤ 500 chars)'
+complete -c pty -n '__pty_using_command run' -l name -d 'Display label (trimmed, single-line, ≤ 160 Unicode scalars)'
 complete -c pty -n '__pty_using_command run' -l no-display-name -d 'Skip the auto-generated label'
 complete -c pty -n '__pty_using_command run' -l tag -d 'Tag session (k=v, repeatable)'
 complete -c pty -n '__pty_using_command run' -l env -d 'Overlay child environment (KEY=VALUE, repeatable)'
diff --git a/completions/pty.zsh b/completions/pty.zsh
index 0e79f2e..3b842ad 100644
--- a/completions/pty.zsh
+++ b/completions/pty.zsh
@@ -59,7 +59,7 @@ _pty() {
             '(a --attach){a,--attach}[Create OR attach if id already exists]' \
             '(e --ephemeral){e,--ephemeral}[Ephemeral: auto-remove metadata on clean exit]' \
             '--id[Pin on-disk id (charset-validated)]' \
-            '--name[Display label (any printable, ≤ 500 chars)]' \
+            '--name[Display label (trimmed, single-line, ≤ 160 Unicode scalars)]' \
             '--no-display-name[Skip the auto-generated label]' \
             '--tag[Tag session (k=v, repeatable)]' \
             '--env[Overlay child environment (KEY=VALUE, repeatable)]' \
diff --git a/docs/client.md b/docs/client.md
index 590ec4d..420da0c 100644
--- a/docs/client.md
+++ b/docs/client.md
@@ -127,7 +127,11 @@ Remove a session's `.sock` and `.pid` files.
 
 ### `cleanupAll(name: string): void`
 
-Remove all files for a session (socket, pid, metadata, events, lock).
+Remove all files for a session (socket, pid, metadata, and events). Cleanup is
+serialized by acquiring the event lock before the metadata/creation lock. It
+throws when either lock has a live holder, changes no session files in that
+case, and removes only locks acquired by the cleanup call. Dead holders' stale
+locks are reclaimed.
 
 ### Types
 
diff --git a/docs/disk-layout.md b/docs/disk-layout.md
index 451cafb..932313f 100644
--- a/docs/disk-layout.md
+++ b/docs/disk-layout.md
@@ -15,6 +15,7 @@ For non-Node tools that want to read pty's state without paying Node startup. Th
 | `<name>.sock` | daemon IPC socket (Unix) | 2 |
 | `<name>.pid` | daemon pid (decimal) | 2 |
 | `<name>.lock` | creation-race lock | 2 |
+| `<name>.events.lock` | event append/retention lock | 2 |
 | `theme` | last-selected TUI theme | 2 |
 | `gc.log` | stdout/stderr of `pty gc` when run by launchd/cron (only present after auto-running gc is installed) | 2 |
 | `<name>.json.tmp.<pid>.<rand>` | atomic-write tmp — readers MUST ignore | n/a |
@@ -103,7 +104,12 @@ Envelope: `{ session: string; type: string; ts: string; ...payload }`. Event typ
 | `metadata_change` | `previous, value` containing only changed `displayName` and tag keys; absent tag values are `null` |
 | `user.<name>` | `data?, text?` — free-form, via `pty emit` |
 
-A single line ≤ `PIPE_BUF` (~4 KB) is atomic per POSIX `O_APPEND`. Built-ins are well under. Keep large `user.*` payloads out of the event stream.
+All event writers and retention rewrites are serialized by the per-session
+event lock. A complete JSONL record is therefore published without relying on
+an operating-system write-size limit, and retention cannot discard an append
+that races its atomic rewrite. Async writers wait up to five seconds for a live
+holder; synchronous writers fail immediately. Lock files are removed on release,
+and a dead holder's stale lock is reclaimed by the next writer or cleanup.
 
 ## Reading from outside pty
 
diff --git a/src/cli.ts b/src/cli.ts
index 2c44f11..07dd83e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -15,6 +15,7 @@ import {
   pruneOrphanLayoutTags,
   isGone,
   cleanupAll,
+  cleanupAllWhileLocked,
   cleanupSocket,
   cleanupOwnedAll,
   waitForProcessExit,
@@ -38,7 +39,7 @@ import {
 } from "./sessions.ts";
 import { spawnDaemon, resolveCommand } from "./spawn.ts";
 import {
-  EventFollower, EventWriter, EventType,
+  acquireEventLock, EventFollower, EventWriter, EventType, releaseEventLock,
   readRecentEvents, formatEvent,
   emitUserEvent,
 } from "./events.ts";
@@ -90,7 +91,7 @@ Create a session and attach to it (use -d to leave it running in the background)
 
 Flags:
   --id <id>            Pin the on-disk id (sock/json filename; charset-validated, ≤ 104-byte sock path)
-  --name <label>       Explicit display label (any printable text, ≤ 500 chars)
+  --name <label>       Display label (trimmed, single-line, ≤ 160 Unicode scalars)
   --no-display-name    Skip the auto cwd+command label — just the id
   -d, --detach         Create in the background; don't attach
   -a, --attach         Create, OR attach if a session with the same id already exists
@@ -422,7 +423,7 @@ function usage(): void {
 Create sessions:
   pty run -- <command> [args...]          Create a session and attach (random id + auto display label)
   pty run --id <id> -- <command>          Pin the on-disk id (sock / json filename; charset-validated)
-  pty run --name <label> -- <command>     Set an explicit display label (any printable, ≤ 500 chars)
+  pty run --name <label> -- <command>     Set a trimmed, single-line display label (≤ 160 Unicode scalars)
   pty run --no-display-name -- <cmd>      Skip the friendly cwd+command label (just an id)
   pty run -d -- <command>                 Create in the background (detached)
   pty run -a -- <command>                 Create OR attach if a session with the same id already exists
@@ -1585,18 +1586,7 @@ async function cmdRun(
   extraEnv: Record<string, string> = {},
   unsetEnv: string[] = [],
 ): Promise<void> {
-  const session = await getSessionByName(name);
-  if (session?.status === "running") {
-    if (attachExisting) {
-      console.log(`Session "${name}" already running, attaching.`);
-      doAttach(name);
-      return;
-    }
-    console.error(
-      `Session "${name}" is already running. Use "pty attach ${name}" to connect.`
-    );
-    process.exit(1);
-  }
+  let session = await getSessionByName(name);
 
   const delegatedOwner = Number(process.env.PTY_CREATION_LOCK_OWNER_PID);
   const inheritedCreationLock =
@@ -1604,9 +1594,41 @@ async function cmdRun(
     isLockOwnedByPid(name, delegatedOwner);
   // This is a one-hop control value for the CLI process, not session env.
   delete process.env.PTY_CREATION_LOCK_OWNER_PID;
-  if (!inheritedCreationLock && !acquireLock(name)) {
+  let ownsEventLock = false;
+  let ownsCreationLock = false;
+  if (!inheritedCreationLock) {
+    if (!acquireEventLock(name)) {
+      console.error(`Session "${name}" event log is busy. Try again.`);
+      process.exit(1);
+    }
+    ownsEventLock = true;
+    if (!acquireLock(name)) {
+      releaseEventLock(name);
+      console.error(
+        `Session "${name}" is being created by another process. Try again.`
+      );
+      process.exit(1);
+    }
+    ownsCreationLock = true;
+    session = await getSessionByName(name);
+  }
+
+  if (session?.status === "running") {
+    if (ownsCreationLock) {
+      releaseLock(name);
+      ownsCreationLock = false;
+    }
+    if (ownsEventLock) {
+      releaseEventLock(name);
+      ownsEventLock = false;
+    }
+    if (attachExisting) {
+      console.log(`Session "${name}" already running, attaching.`);
+      doAttach(name);
+      return;
+    }
     console.error(
-      `Session "${name}" is being created by another process. Try again.`
+      `Session "${name}" is already running. Use "pty attach ${name}" to connect.`
     );
     process.exit(1);
   }
@@ -1617,11 +1639,14 @@ async function cmdRun(
   const previousTags = session && isGone(session.status) ? session.metadata?.tags : undefined;
   const previousExtraEnv = session && isGone(session.status) ? session.metadata?.extraEnv : undefined;
   const previousUnsetEnv = session && isGone(session.status) ? session.metadata?.unsetEnv : undefined;
-  if (session && isGone(session.status)) {
-    cleanupAll(name);
-  }
-
   try {
+    if (session && isGone(session.status) && !inheritedCreationLock) {
+      cleanupAllWhileLocked(name);
+    }
+    if (ownsEventLock) {
+      releaseEventLock(name);
+      ownsEventLock = false;
+    }
     const tagOpt = Object.keys(tags).length > 0 ? tags : previousTags;
     const cwdOpt = explicitCwd ?? previousCwd;
     // If the session had a previous displayName (e.g., it was renamed before
@@ -1633,13 +1658,15 @@ async function cmdRun(
     const unsetEnvOpt = unsetEnv.length > 0 ? unsetEnv : previousUnsetEnv;
     await spawnDaemon({
       name, command, args, displayCommand, cwd: cwdOpt, ephemeral, tags: tagOpt,
+      creationLockOwnerPid: inheritedCreationLock ? delegatedOwner : process.pid,
       ...(displayNameOpt ? { displayName: displayNameOpt } : {}),
       ...(isolateEnv ? { isolateEnv: true } : {}),
       ...(extraEnvOpt && Object.keys(extraEnvOpt).length > 0 ? { extraEnv: extraEnvOpt } : {}),
       ...(unsetEnvOpt && unsetEnvOpt.length > 0 ? { unsetEnv: unsetEnvOpt } : {}),
     });
   } finally {
-    if (!inheritedCreationLock) releaseLock(name);
+    if (ownsEventLock) releaseEventLock(name);
+    if (ownsCreationLock) releaseLock(name);
   }
 
   console.log(`Session "${name}" created.`);
@@ -2683,9 +2710,8 @@ async function cmdRename(rawArgs: string[]): Promise<void> {
     process.exit(1);
   }
 
-  // Display names can be arbitrary printable text (spaces, punctuation, any
-  // length up to 500 chars). The on-disk id (`name`) carries the strict
-  // charset and the sock-path-length constraint; display names don't.
+  // Display names are bounded, single-line presentation metadata. The on-disk
+  // id (`name`) carries the strict charset and sock-path-length constraint.
   try {
     validateDisplayName(newDisplay);
   } catch (e: any) {
@@ -3358,7 +3384,14 @@ async function cmdUp(dir: string | undefined, names: string[]): Promise<void> {
 
     // Clean up an exited bound session so its slot can be reused.
     if (bound && isGone(bound.status)) {
-      cleanupAll(bound.name);
+      const label = bound.metadata?.displayName ?? bound.name;
+      try {
+        cleanupAll(bound.name);
+      } catch (error) {
+        console.error(`  ✗ ${label}: ${(error as Error).message}`);
+        skipped++;
+        continue;
+      }
     }
 
     // Pick the on-disk id: honor the pty.toml's `id = "..."` if set,
@@ -3473,9 +3506,13 @@ async function cmdDown(dir: string | undefined, names: string[]): Promise<void>
       }
       cleanupSocket(existingSession.name);
     } else if (isGone(existingSession.status)) {
-      cleanupAll(existingSession.name);
-      console.log(`  ○ ${label} (cleaned up)`);
-      stopped++;
+      try {
+        cleanupAll(existingSession.name);
+        console.log(`  ○ ${label} (cleaned up)`);
+        stopped++;
+      } catch (error) {
+        console.error(`  ✗ ${label}: ${(error as Error).message}`);
+      }
     }
   }
 
diff --git a/src/completions.ts b/src/completions.ts
index 538bd0c..6aaae85 100644
--- a/src/completions.ts
+++ b/src/completions.ts
@@ -69,7 +69,7 @@ const COMMANDS: readonly CommandSpec[] = [
       { name: "attach", short: "a", desc: "Create OR attach if id already exists" },
       { name: "ephemeral", short: "e", desc: "Ephemeral: auto-remove metadata on clean exit" },
       { name: "id", desc: "Pin on-disk id (charset-validated)" },
-      { name: "name", desc: "Display label (any printable, ≤ 500 chars)" },
+      { name: "name", desc: "Display label (trimmed, single-line, ≤ 160 Unicode scalars)" },
       { name: "no-display-name", desc: "Skip the auto-generated label" },
       { name: "tag", desc: "Tag session (k=v, repeatable)" },
       { name: "env", desc: "Overlay child environment (KEY=VALUE, repeatable)" },
diff --git a/src/events.ts b/src/events.ts
index 9551fbc..0e05b1d 100644
--- a/src/events.ts
+++ b/src/events.ts
@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
+import * as path from "node:path";
 import {
   getEventsPath, getSessionDir, ensureSessionDir,
   atomicWriteFileSync, atomicWriteFile,
+  acquireFileLock, releaseFileLock,
 } from "./sessions.ts";
 
 export const EventType = {
@@ -217,6 +219,43 @@ export function validateUserEventType(type: string): string | null {
 const MAX_LINES = 1000;
 const KEEP_LINES = 500;
 const TRUNCATE_CHECK_INTERVAL = 100;
+const EVENT_LOCK_WAIT_MS = 5_000;
+
+function getEventLockPath(name: string): string {
+  return path.join(getSessionDir(), `${name}.events.lock`);
+}
+
+export function acquireEventLock(name: string): boolean {
+  return acquireFileLock(getEventLockPath(name));
+}
+
+export function releaseEventLock(name: string): void {
+  releaseFileLock(getEventLockPath(name));
+}
+
+/** @internal Acquire with bounded polling for async writers. */
+export async function waitForEventLock(
+  name: string,
+  waitMs = EVENT_LOCK_WAIT_MS,
+): Promise<void> {
+  const deadline = Date.now() + waitMs;
+  while (!acquireEventLock(name)) {
+    if (Date.now() >= deadline) {
+      throw new Error(`Session id "${name}" event log is busy. Retry the operation.`);
+    }
+    const delayMs = Math.min(10, deadline - Date.now());
+    await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+  }
+}
+
+async function withEventLock<T>(name: string, operation: () => Promise<T>): Promise<T> {
+  await waitForEventLock(name);
+  try {
+    return await operation();
+  } finally {
+    releaseEventLock(name);
+  }
+}
 
 /** One-shot helper to append a single event to a session's events log
  *  without keeping an EventWriter around. Used by CLI subcommands like
@@ -226,24 +265,17 @@ const TRUNCATE_CHECK_INTERVAL = 100;
  *  truncate path is skipped via a cheap stat when the file is small. */
 export async function appendEvent(name: string, event: EventRecord): Promise<void> {
   ensureSessionDir();
-  const filePath = getEventsPath(name);
-  const line = JSON.stringify(event) + "\n";
-  await fsp.appendFile(filePath, line);
-  await maybeTruncate(filePath);
+  await withEventLock(name, async () => {
+    const filePath = getEventsPath(name);
+    const line = JSON.stringify(event) + "\n";
+    await fsp.appendFile(filePath, line);
+    await maybeTruncate(filePath);
+  });
 }
 
-/** Synchronous twin of `appendEvent` — lets synchronous metadata-mutation
- *  helpers (setDisplayName, updateTags) emit their change events inline
- *  without forcing their signatures to go async. Uses the same retention
- *  path with a sync stat fast-path.
- *
- *  Concurrency note: `fs.appendFileSync` issues a single `write()` with
- *  `O_APPEND`, which POSIX guarantees is atomic for payloads up to
- *  `PIPE_BUF` bytes (typically 4096 on Linux/macOS). All built-in events
- *  are well under that. If a caller passes a large `user.*` event
- *  payload, concurrent appends could interleave — keep large payloads
- *  out of the event stream. */
-export function appendEventSync(name: string, event: EventRecord): void {
+/** Append while the caller owns this session's event lock. This supports
+ *  transactions that must acquire the event lock before another lock. */
+export function appendEventSyncLocked(name: string, event: EventRecord): void {
   ensureSessionDir();
   const filePath = getEventsPath(name);
   const line = JSON.stringify(event) + "\n";
@@ -251,6 +283,17 @@ export function appendEventSync(name: string, event: EventRecord): void {
   maybeTruncateSync(filePath);
 }
 
+export function appendEventSync(name: string, event: EventRecord): void {
+  if (!acquireEventLock(name)) {
+    throw new Error(`Session id "${name}" event log is busy. Retry the operation.`);
+  }
+  try {
+    appendEventSyncLocked(name, event);
+  } finally {
+    releaseEventLock(name);
+  }
+}
+
 function maybeTruncateSync(filePath: string): void {
   try {
     const stat = fs.statSync(filePath);
@@ -258,11 +301,8 @@ function maybeTruncateSync(filePath: string): void {
     const content = fs.readFileSync(filePath, "utf-8");
     const lines = content.trimEnd().split("\n");
     if (lines.length >= MAX_LINES) {
-      // Tmp+rename so readers never see a half-written rewrite. Concurrent
-      // appenders after our read but before our rename will have their
-      // lines lost (their append goes to the old inode that we unlink
-      // via rename); that's a "concurrent writes overwrite each other"
-      // case, not corruption — readers always see a valid JSONL file.
+      // The event lock spans the read and atomic replacement, so appends
+      // cannot target the old inode between those operations.
       atomicWriteFileSync(filePath, lines.slice(-KEEP_LINES).join("\n") + "\n");
     }
   } catch {
@@ -321,17 +361,15 @@ export class EventWriter {
   /** Queue an event for writing. Returns immediately; I/O happens async. */
   append(event: EventRecord): void {
     this.chain = this.chain
-      .then(() => {
+      .then(() => withEventLock(this.name, async () => {
         const line = JSON.stringify(event) + "\n";
-        return fsp.appendFile(getEventsPath(this.name), line);
-      })
-      .then(() => {
+        await fsp.appendFile(getEventsPath(this.name), line);
         this.appendCount++;
         if (this.appendCount >= TRUNCATE_CHECK_INTERVAL) {
           this.appendCount = 0;
-          return truncate(getEventsPath(this.name));
+          await truncate(getEventsPath(this.name));
         }
-      })
+      }))
       .catch(() => {});
   }
 
@@ -345,23 +383,33 @@ async function truncate(filePath: string): Promise<void> {
   const content = await fsp.readFile(filePath, "utf-8");
   const lines = content.trimEnd().split("\n");
   if (lines.length >= MAX_LINES) {
-    // Tmp+rename so readers never see a half-written rewrite — same
-    // reasoning as `maybeTruncateSync`.
+    // Tmp+rename so readers never see a half-written rewrite. The caller
+    // holds the event lock across the read and replacement.
     await atomicWriteFile(filePath, lines.slice(-KEEP_LINES).join("\n") + "\n");
   }
 }
 
 export function clearEvents(name: string): void {
   ensureSessionDir();
+  if (!acquireEventLock(name)) {
+    throw new Error(`Session id "${name}" event log is busy. Retry the operation.`);
+  }
   try {
     fs.writeFileSync(getEventsPath(name), "");
-  } catch {}
+  } catch {} finally {
+    releaseEventLock(name);
+  }
 }
 
 export function removeEvents(name: string): void {
+  if (!acquireEventLock(name)) {
+    throw new Error(`Session id "${name}" event log is busy. Retry the operation.`);
+  }
   try {
     fs.unlinkSync(getEventsPath(name));
-  } catch {}
+  } catch {} finally {
+    releaseEventLock(name);
+  }
 }
 
 export function readRecentEvents(name: string, count = 50): EventRecord[] {
diff --git a/src/server.ts b/src/server.ts
index 438a569..4bde720 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -22,15 +22,16 @@ import {
 import {
   getSocketPath,
   getPidPath,
-  getMetadataPath,
   ensureSessionDir,
   cleanupOwnedSocket,
   cleanupOwnedAll,
   writeMetadata,
   readMetadata,
+  mutateMetadataUnderLock,
   shouldReapAtExit,
   reapOnExitDefault,
   type SessionMetadata,
+  type MetadataMutationResult,
 } from "./sessions.ts";
 import { EventWriter, clearEvents, EventType, type EventRecord } from "./events.ts";
 import type { StatsResult } from "./client.ts";
@@ -541,7 +542,13 @@ export class PtyServer {
       // in pty list during the cleanup window. lastLines may be incomplete
       // here since PTY data could still be in-flight — close() will
       // update with the final output.
-      this.saveExitMetadata(code);
+      const exitMetadataStatus = this.saveExitMetadata(code);
+      if (exitMetadataStatus === "busy" || exitMetadataStatus === "stale") {
+        // Startup may still hold the creation lock for this generation. Retry
+        // within the existing 500ms client grace so exit metadata is observable
+        // before shutdown cleanup, while close() retains the final bounded retry.
+        void this.saveExitMetadataUntilSettled(code, 400).catch(() => {});
+      }
       this.resolveChildExited();
       options.onExit?.(code);
     });
@@ -653,20 +660,13 @@ export class PtyServer {
             if (!resized) {
               socket.write(encodeGeometry(this.terminal.rows, this.terminal.cols));
             }
-            // Stamp the last-attach timestamp so `pty gc --idle-days N`
-            // (and per-session `strategy.idle-days=N` tags) can detect
-            // abandonment. Best-effort — if the metadata file was
-            // concurrently mutated by another writer (`pty tag`,
-            // `pty rename`), our read-modify-write may lose a field, but
-            // that's the same last-write-wins semantic every other
-            // metadata mutation carries. Wrapped in try so a torn read
-            // never crashes the daemon on attach.
+            // Best-effort: a concurrent metadata command wins this attach
+            // stamp, but neither writer can overwrite the other's snapshot.
             try {
-              const meta = readMetadata(this.name);
-              if (meta) {
+              mutateMetadataUnderLock(this.name, (meta) => {
                 meta.lastAttachAt = new Date().toISOString();
-                writeMetadata(this.name, meta);
-              }
+                return true;
+              }, { expectedGeneration: this.generation });
             } catch {}
 
             const sendScreen = () => {
@@ -1022,40 +1022,32 @@ export class PtyServer {
     return lines.slice(-LAST_LINES_COUNT);
   }
 
-  private saveExitMetadata(exitCode: number): void {
-    // Don't resurrect a session whose metadata was already removed. On teardown
-    // the daemon re-flushes exit metadata during its (possibly watchdog-delayed)
-    // shutdown; if a caller already `pty rm`'d the session, re-creating its
-    // `.json` here would leave a stray registry file (and its atomic tmp) behind.
-    if (!fs.existsSync(getMetadataPath(this.name))) return;
-    const existing = readMetadata(this.name);
-    if (
-      existing?.generation !== undefined &&
-      existing.generation !== this.generation
-    ) {
-      return;
+  private saveExitMetadata(exitCode: number): MetadataMutationResult["status"] {
+    const result = mutateMetadataUnderLock(this.name, (metadata) => {
+      metadata.exitCode = exitCode;
+      metadata.exitedAt = new Date().toISOString();
+      metadata.lastLines = this.getLastLines();
+      return true;
+    }, { expectedGeneration: this.generation });
+    return result.status;
+  }
+
+  private async saveExitMetadataUntilSettled(
+    exitCode: number,
+    waitMs = 2_000,
+  ): Promise<void> {
+    const deadline = Date.now() + waitMs;
+    while (true) {
+      const status = this.saveExitMetadata(exitCode);
+      if (
+        status === "changed" ||
+        status === "unchanged" ||
+        status === "missing" ||
+        status === "generation-mismatch"
+      ) return;
+      if (Date.now() >= deadline) return;
+      await new Promise((resolve) => setTimeout(resolve, 10));
     }
-    writeMetadata(this.name, {
-      generation: this.generation,
-      daemonPid: process.pid,
-      command: this.options.command,
-      args: this.options.args,
-      displayCommand: this.options.displayCommand,
-      cwd: this.options.cwd,
-      rows: this.options.rows,
-      cols: this.options.cols,
-      ephemeral: this.options.ephemeral === true,
-      createdAt: existing?.createdAt ?? new Date().toISOString(),
-      exitCode,
-      exitedAt: new Date().toISOString(),
-      lastLines: this.getLastLines(),
-      ...(existing?.tags ? { tags: existing.tags } : {}),
-      ...(existing?.displayName ? { displayName: existing.displayName } : {}),
-      ...(this.options.isolateEnv ? { isolateEnv: true } : {}),
-      ...(this.options.extraEnv && Object.keys(this.options.extraEnv).length > 0 ? { extraEnv: this.options.extraEnv } : {}),
-      ...(this.options.unsetEnv && this.options.unsetEnv.length > 0 ? { unsetEnv: this.options.unsetEnv } : {}),
-      ...(this.options.env ? { env: this.options.env } : {}),
-    });
   }
 
   /** Clean up resources. Does not call process.exit(). */
@@ -1088,6 +1080,7 @@ export class PtyServer {
           this.childExited,
           new Promise<void>((r) => setTimeout(r, 2000)),
         ]);
+        if (this.exited) await this.saveExitMetadataUntilSettled(this.exitCode);
         try { await this.eventWriter.flush(); } catch {}
         resolve();
       });
diff --git a/src/sessions.ts b/src/sessions.ts
index a3f76de..83ff484 100644
--- a/src/sessions.ts
+++ b/src/sessions.ts
@@ -7,7 +7,9 @@ import { createHash } from "node:crypto";
 // Circular import: events.ts imports getEventsPath/ensureSessionDir from
 // this file. Cycle is safe — `appendEventSync` is only called at runtime
 // from inside functions, never at module-init time.
-import { appendEventSync } from "./events.ts";
+import {
+  acquireEventLock, appendEventSync, appendEventSyncLocked, releaseEventLock,
+} from "./events.ts";
 
 export const DEFAULT_SESSION_DIR = path.join(os.homedir(), ".local", "state", "pty");
 
@@ -48,22 +50,19 @@ export function validateName(name: string): void {
   }
 }
 
-/** Permissive validator for display labels. Allowed: anything printable
- *  including spaces and punctuation, ≤ 500 chars. Rejected: empty, NUL,
- *  slashes (would confuse path-shaped UIs), backslashes, newlines, other
- *  control characters. Length cap is a sanity limit, not a kernel limit —
- *  display labels live in metadata.json, not in the socket path. */
+/** Validate mutable presentation metadata independently of stable session ids. */
 export function validateDisplayName(name: string): void {
-  if (!name || name.length === 0) {
+  if (name.length === 0) {
     throw new Error("Display name cannot be empty.");
   }
-  if (name.length > 500) {
-    throw new Error("Display name too long (max 500 characters).");
+  if (name !== name.trim()) {
+    throw new Error("Display name must be trimmed.");
   }
-  if (/[\0\/\\\n\r\t\x00-\x1f\x7f]/.test(name)) {
-    throw new Error(
-      `Invalid display name. Slashes, backslashes, newlines, and control characters are not allowed.`
-    );
+  if (Array.from(name).length > 160) {
+    throw new Error("Display name too long (max 160 Unicode scalars).");
+  }
+  if (/[\p{Cc}\u2028\u2029]/u.test(name)) {
+    throw new Error("Display name must be single-line and contain no control characters.");
   }
 }
 
@@ -254,6 +253,55 @@ type MetadataChangeSnapshot = {
 
 type MetadataPatchEvent = "metadata_change" | "display_name_change" | "tags_change";
 
+export type MetadataMutationResult =
+  | { status: "changed"; metadata: SessionMetadata }
+  | { status: "unchanged"; metadata: SessionMetadata }
+  | { status: "busy" }
+  | { status: "missing" }
+  | { status: "generation-mismatch" }
+  | { status: "stale" };
+
+/** Serialize one whole-record metadata mutation against lifecycle writers. */
+export function mutateMetadataUnderLock(
+  name: string,
+  mutate: (metadata: SessionMetadata) => boolean,
+  options: {
+    expectedGeneration?: string;
+    onPublished?: (metadata: SessionMetadata) => void;
+  } = {},
+): MetadataMutationResult {
+  if (!acquireLock(name)) return { status: "busy" };
+
+  try {
+    const metadata = readMetadata(name);
+    if (!metadata) return { status: "missing" };
+    if (
+      options.expectedGeneration !== undefined &&
+      metadata.generation !== options.expectedGeneration
+    ) {
+      return { status: "generation-mismatch" };
+    }
+
+    const observed = JSON.stringify(metadata);
+    if (!mutate(metadata)) return { status: "unchanged", metadata };
+
+    const latest = readMetadata(name);
+    if (!latest || JSON.stringify(latest) !== observed) return { status: "stale" };
+    if (
+      options.expectedGeneration !== undefined &&
+      latest.generation !== options.expectedGeneration
+    ) {
+      return { status: "generation-mismatch" };
+    }
+
+    writeMetadata(name, metadata);
+    options.onPublished?.(metadata);
+    return { status: "changed", metadata };
+  } finally {
+    releaseLock(name);
+  }
+}
+
 function validateMetadataPatch(patch: unknown): asserts patch is MetadataPatch {
   if (patch === null || typeof patch !== "object" || Array.isArray(patch)) {
     throw new Error("Metadata patch must be a JSON object.");
@@ -305,100 +353,110 @@ function applyMetadataPatchById(
   eventType: MetadataPatchEvent,
 ): MetadataPatchResult {
   validateMetadataPatch(patch);
-  if (!acquireLock(id)) {
-    throw new Error(`Session id "${id}" metadata is busy. Retry the operation.`);
+  if (!acquireEventLock(id)) {
+    throw new Error(`Session id "${id}" event log is busy. Retry the operation.`);
   }
-
   try {
-    const metadata = readMetadata(id);
-    if (!metadata) throw new Error(`Session id "${id}" not found.`);
-
-    const previousTags = Object.fromEntries(Object.entries(metadata.tags ?? {}));
-    const nextTags = Object.fromEntries(Object.entries(previousTags));
+    let previousTags: Record<string, string> = {};
+    let nextTags: Record<string, string> = {};
     const previous: MetadataChangeSnapshot = {};
     const value: MetadataChangeSnapshot = {};
-
-    if (Object.prototype.hasOwnProperty.call(patch, "displayName")) {
-      const before = metadata.displayName ?? null;
-      const after = patch.displayName ?? null;
-      if (before !== after) {
-        previous.displayName = before;
-        value.displayName = after;
-        if (after === null) delete metadata.displayName;
-        else metadata.displayName = after;
+    const result = mutateMetadataUnderLock(id, (metadata) => {
+      previousTags = Object.fromEntries(Object.entries(metadata.tags ?? {}));
+      nextTags = Object.fromEntries(Object.entries(previousTags));
+      if (Object.prototype.hasOwnProperty.call(patch, "displayName")) {
+        const before = metadata.displayName ?? null;
+        const after = patch.displayName ?? null;
+        if (before !== after) {
+          previous.displayName = before;
+          value.displayName = after;
+          if (after === null) delete metadata.displayName;
+          else metadata.displayName = after;
+        }
       }
-    }
 
-    if (patch.tags !== undefined) {
-      const changedTagKeys: string[] = [];
-      for (const [key, requested] of Object.entries(patch.tags)) {
-        const before = Object.prototype.hasOwnProperty.call(previousTags, key)
-          ? previousTags[key]
-          : null;
-        const after = requested ?? null;
-        if (before === after) continue;
-        changedTagKeys.push(key);
-        if (after === null) delete nextTags[key];
-        else setRecordValue(nextTags, key, after);
-      }
-      if (changedTagKeys.length > 0) {
-        previous.tags = {};
-        value.tags = {};
-        for (const key of changedTagKeys.sort()) {
+      if (patch.tags !== undefined) {
+        const changedTagKeys: string[] = [];
+        for (const [key, requested] of Object.entries(patch.tags)) {
           const before = Object.prototype.hasOwnProperty.call(previousTags, key)
             ? previousTags[key]
             : null;
-          const after = Object.prototype.hasOwnProperty.call(nextTags, key)
-            ? nextTags[key]
-            : null;
-          Object.defineProperty(previous.tags, key, { value: before, enumerable: true });
-          Object.defineProperty(value.tags, key, { value: after, enumerable: true });
+          const after = requested ?? null;
+          if (before === after) continue;
+          changedTagKeys.push(key);
+          if (after === null) delete nextTags[key];
+          else setRecordValue(nextTags, key, after);
+        }
+        if (changedTagKeys.length > 0) {
+          previous.tags = {};
+          value.tags = {};
+          for (const key of changedTagKeys.sort()) {
+            const before = Object.prototype.hasOwnProperty.call(previousTags, key)
+              ? previousTags[key]
+              : null;
+            const after = Object.prototype.hasOwnProperty.call(nextTags, key)
+              ? nextTags[key]
+              : null;
+            Object.defineProperty(previous.tags, key, { value: before, enumerable: true });
+            Object.defineProperty(value.tags, key, { value: after, enumerable: true });
+          }
+          if (Object.keys(nextTags).length === 0) delete metadata.tags;
+          else metadata.tags = nextTags;
         }
-        if (Object.keys(nextTags).length === 0) delete metadata.tags;
-        else metadata.tags = nextTags;
       }
-    }
 
-    const changed = Object.keys(previous).length > 0;
-    if (!changed) return { changed: false, metadata };
+      const changed = Object.keys(previous).length > 0;
+      if (!changed) return false;
 
-    if (metadata.displayName !== undefined) validateDisplayName(metadata.displayName);
-    for (const [key, tagValue] of Object.entries(metadata.tags ?? {})) {
-      if (key.length === 0) throw new Error("Resulting metadata contains an empty tag key.");
-      if (typeof tagValue !== "string") {
-        throw new Error(`Resulting metadata tag "${key}" is not a string.`);
+      if (metadata.displayName !== undefined) validateDisplayName(metadata.displayName);
+      for (const [key, tagValue] of Object.entries(metadata.tags ?? {})) {
+        if (key.length === 0) throw new Error("Resulting metadata contains an empty tag key.");
+        if (typeof tagValue !== "string") {
+          throw new Error(`Resulting metadata tag "${key}" is not a string.`);
+        }
       }
-    }
 
-    writeMetadata(id, metadata);
-    if (eventType === "metadata_change") {
-      appendEventSync(id, {
-        session: id,
-        type: "metadata_change",
-        ts: new Date().toISOString(),
-        previous,
-        value,
-      });
-    } else if (eventType === "display_name_change") {
-      appendEventSync(id, {
-        session: id,
-        type: "display_name_change",
-        ts: new Date().toISOString(),
-        previous: previous.displayName ?? null,
-        value: value.displayName ?? null,
-      });
-    } else {
-      appendEventSync(id, {
-        session: id,
-        type: "tags_change",
-        ts: new Date().toISOString(),
-        previous: previousTags,
-        value: nextTags,
-      });
+      return true;
+    }, {
+      onPublished: () => {
+        if (eventType === "metadata_change") {
+          appendEventSyncLocked(id, {
+            session: id,
+            type: "metadata_change",
+            ts: new Date().toISOString(),
+            previous,
+            value,
+          });
+        } else if (eventType === "display_name_change") {
+          appendEventSyncLocked(id, {
+            session: id,
+            type: "display_name_change",
+            ts: new Date().toISOString(),
+            previous: previous.displayName ?? null,
+            value: value.displayName ?? null,
+          });
+        } else {
+          appendEventSyncLocked(id, {
+            session: id,
+            type: "tags_change",
+            ts: new Date().toISOString(),
+            previous: previousTags,
+            value: nextTags,
+          });
+        }
+      },
+    });
+
+    if (result.status === "busy") {
+      throw new Error(`Session id "${id}" metadata is busy. Retry the operation.`);
     }
-    return { changed: true, metadata };
+    if (result.status === "missing") throw new Error(`Session id "${id}" not found.`);
+    if (result.status === "stale" || result.status === "generation-mismatch") {
+      throw new Error(`Session id "${id}" metadata changed during the operation. Retry it.`);
+    }
+    return { changed: result.status === "changed", metadata: result.metadata };
   } finally {
-    releaseLock(id);
+    releaseEventLock(id);
   }
 }
 
@@ -555,7 +613,11 @@ export async function cleanupRawCandidateGuarded(
   candidate: RawCleanupCandidate,
   options: ListSessionsOptions = {},
 ): Promise<boolean> {
-  if (!acquireLock(candidate.name)) return false;
+  if (!acquireEventLock(candidate.name)) return false;
+  if (!acquireLock(candidate.name)) {
+    releaseEventLock(candidate.name);
+    return false;
+  }
   try {
     const current = await inventoryRawCleanupCandidates(
       options,
@@ -573,6 +635,7 @@ export async function cleanupRawCandidateGuarded(
     return true;
   } finally {
     releaseLock(candidate.name);
+    releaseEventLock(candidate.name);
   }
 }
 
@@ -590,7 +653,8 @@ function metadataMatchesObservation(
   return JSON.stringify(observed) === JSON.stringify(current);
 }
 
-function cleanupAllWhileLocked(name: string): void {
+/** @internal Remove session artifacts while the caller owns both event and metadata locks. */
+export function cleanupAllWhileLocked(name: string): void {
   cleanupSocket(name);
   try {
     fs.unlinkSync(getMetadataPath(name));
@@ -604,7 +668,11 @@ function cleanupAllWhileLocked(name: string): void {
 export async function cleanupObservedSession(
   session: SessionInfo,
 ): Promise<boolean> {
-  if (!session.metadata || !acquireLock(session.name)) return false;
+  if (!session.metadata || !acquireEventLock(session.name)) return false;
+  if (!acquireLock(session.name)) {
+    releaseEventLock(session.name);
+    return false;
+  }
   try {
     const current = readMetadata(session.name);
     if (
@@ -617,6 +685,7 @@ export async function cleanupObservedSession(
     return true;
   } finally {
     releaseLock(session.name);
+    releaseEventLock(session.name);
   }
 }
 
@@ -1027,7 +1096,11 @@ export async function gc(
           await new Promise((r) => setTimeout(r, 25));
         }
       }
-      cleanupAll(s.name);
+      try {
+        cleanupAll(s.name);
+      } catch {
+        continue;
+      }
     }
     killedOrphanChildren.push({ name: s.name, parent: parentRef, reason });
   }
@@ -1065,7 +1138,11 @@ export async function gc(
           ...(decision.idleDays !== undefined ? { idleDays: decision.idleDays } : {}),
         });
       } catch {}
-      cleanupAll(s.name);
+      try {
+        cleanupAll(s.name);
+      } catch {
+        continue;
+      }
     }
     abandoned.push({
       name: s.name,
@@ -1450,7 +1527,12 @@ export async function respawnPermanent(
   // Serialize compare-and-swap cleanup + replacement creation under the same
   // per-name lock. If the observed generation changed while gc was planning,
   // this tick is stale and must not touch the replacement.
-  if (!acquireLock(name)) return false;
+  if (!acquireEventLock(name)) return false;
+  if (!acquireLock(name)) {
+    releaseEventLock(name);
+    return false;
+  }
+  let eventLocked = true;
   try {
     const current = readMetadata(name);
     if (!current || !metadataMatchesObservation(metadata, current)) {
@@ -1461,6 +1543,8 @@ export async function respawnPermanent(
     // over leftovers from the dead daemon. Keep the creation lock held until
     // the replacement has published its socket.
     cleanupAllWhileLocked(name);
+    releaseEventLock(name);
+    eventLocked = false;
 
     const { spawnDaemon } = await import("./spawn.ts");
     await spawnDaemon({
@@ -1477,6 +1561,7 @@ export async function respawnPermanent(
     });
   } finally {
     releaseLock(name);
+    if (eventLocked) releaseEventLock(name);
   }
 
   // Best-effort event; respawn already succeeded if we got here.
@@ -1650,14 +1735,25 @@ export function cleanupSocket(name: string): void {
 
 /** Remove everything including metadata. */
 export function cleanupAll(name: string): void {
-  cleanupSocket(name);
-  try {
-    fs.unlinkSync(getMetadataPath(name));
-  } catch {}
+  if (!acquireEventLock(name)) {
+    throw new Error(`Session id "${name}" event log is busy. Retry the operation.`);
+  }
+  if (!acquireLock(name)) {
+    releaseEventLock(name);
+    throw new Error(`Session id "${name}" metadata is busy. Retry the operation.`);
+  }
   try {
-    fs.unlinkSync(getEventsPath(name));
-  } catch {}
-  releaseLock(name);
+    cleanupSocket(name);
+    try {
+      fs.unlinkSync(getMetadataPath(name));
+    } catch {}
+    try {
+      fs.unlinkSync(getEventsPath(name));
+    } catch {}
+  } finally {
+    releaseLock(name);
+    releaseEventLock(name);
+  }
 }
 
 export interface SessionGenerationOwner {
@@ -1700,7 +1796,11 @@ export function cleanupOwnedSocket(name: string, owner: SessionGenerationOwner):
 
 /** Generation-safe full cleanup used by a daemon reaping its own session. */
 export function cleanupOwnedAll(name: string, owner: SessionGenerationOwner): boolean {
-  if (!acquireLock(name)) return false;
+  if (!acquireEventLock(name)) return false;
+  if (!acquireLock(name)) {
+    releaseEventLock(name);
+    return false;
+  }
   try {
     if (!isCurrentGenerationOwner(name, owner)) return false;
     cleanupSocket(name);
@@ -1713,6 +1813,7 @@ export function cleanupOwnedAll(name: string, owner: SessionGenerationOwner): bo
     return true;
   } finally {
     releaseLock(name);
+    releaseEventLock(name);
   }
 }
 
@@ -1732,8 +1833,7 @@ export function isLockOwnedByPid(name: string, ownerPid: number): boolean {
 }
 
 /**
- * Acquire an exclusive lock for a session name. Prevents concurrent
- * `pty run` calls from racing to create the same session.
+ * Acquire an exclusive filesystem lock at an exact path.
  * Returns true if acquired, false if another process holds it.
  *
  * BUG-2 fix: the whole acquisition is built on `open(O_CREAT|O_EXCL)` via
@@ -1742,9 +1842,8 @@ export function isLockOwnedByPid(name: string, ownerPid: number): boolean {
  * unlink it and retry the exclusive open: whichever process wins the
  * post-unlink open owns the lock; the other gets EEXIST and gives up.
  */
-export function acquireLock(name: string): boolean {
+export function acquireFileLock(lockPath: string): boolean {
   ensureSessionDir();
-  const lockPath = getLockPath(name);
 
   const tryCreate = (): boolean => {
     try {
@@ -1788,11 +1887,19 @@ export function acquireLock(name: string): boolean {
   return tryCreate();
 }
 
-export function releaseLock(name: string): void {
+export function releaseFileLock(lockPath: string): void {
   try {
-    fs.unlinkSync(getLockPath(name));
+    fs.unlinkSync(lockPath);
   } catch {}
 }
 
+export function acquireLock(name: string): boolean {
+  return acquireFileLock(getLockPath(name));
+}
+
+export function releaseLock(name: string): void {
+  releaseFileLock(getLockPath(name));
+}
+
 // Keep backward compat for server.ts close()
 export { cleanupSocket as cleanup };
diff --git a/src/spawn.ts b/src/spawn.ts
index 76c3c01..0f77ac9 100644
--- a/src/spawn.ts
+++ b/src/spawn.ts
@@ -3,7 +3,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as tty from "node:tty";
 import { fileURLToPath } from "node:url";
-import { getSocketPath } from "./sessions.ts";
+import {
+  acquireLock, getEventsPath, getSocketPath, readMetadata, releaseLock,
+  validateDisplayName,
+} from "./sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -133,6 +136,7 @@ function resolveSpawnStrategy(): SpawnStrategy {
 }
 
 export async function spawnDaemon(options: SpawnDaemonOptions): Promise<void> {
+  if (options.displayName !== undefined) validateDisplayName(options.displayName);
   if (options.env && (options.isolateEnv || options.extraEnv || options.unsetEnv?.length)) {
     throw new Error(
       "SpawnDaemonOptions.env is mutually exclusive with isolateEnv/extraEnv/unsetEnv. " +
@@ -144,6 +148,19 @@ export async function spawnDaemon(options: SpawnDaemonOptions): Promise<void> {
   return spawnViaNode(options, strategy.serverModule);
 }
 
+/** @internal Own the creation lease through daemon publication. */
+export async function spawnDaemonWithCreationLock(
+  options: SpawnDaemonOptions,
+): Promise<boolean> {
+  if (!acquireLock(options.name)) return false;
+  try {
+    await spawnDaemon({ ...options, creationLockOwnerPid: process.pid });
+    return true;
+  } finally {
+    releaseLock(options.name);
+  }
+}
+
 async function spawnViaNode(options: SpawnDaemonOptions, serverModule: string): Promise<void> {
   const stdout = process.stdout as tty.WriteStream;
   const rows = options.rows ?? stdout.rows ?? 24;
@@ -195,13 +212,28 @@ async function spawnViaNode(options: SpawnDaemonOptions, serverModule: string):
   child.unref();
 
   try {
-    await waitForSocket(options.name, options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS, () => {
+    const timeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+    const startedAt = Date.now();
+    const checkEarlyExit = () => {
       if (earlyExit) {
         const details = stderrOutput.trim();
         const msg = `Daemon process exited immediately (code ${earlyExitCode ?? "unknown"}).`;
         throw new Error(details ? `${msg}\n${details}` : `${msg} Is the command valid?`);
       }
-    });
+    };
+    await waitForSocket(options.name, timeoutMs, checkEarlyExit);
+    while (true) {
+      const metadata = readMetadata(options.name);
+      const startPublished = metadata !== null &&
+        metadata.daemonPid === child.pid &&
+        hasPublishedSessionStart(options.name, metadata.createdAt);
+      if (startPublished) break;
+      checkEarlyExit();
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new Error(`Timed out waiting for daemon publication for session "${options.name}".`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
   } catch (err) {
     if (!earlyExit && child.pid) {
       try { process.kill(child.pid, "SIGTERM"); } catch {}
@@ -210,6 +242,23 @@ async function spawnViaNode(options: SpawnDaemonOptions, serverModule: string):
   }
 }
 
+function hasPublishedSessionStart(name: string, createdAt: string): boolean {
+  try {
+    return fs.readFileSync(getEventsPath(name), "utf8")
+      .trimEnd()
+      .split("\n")
+      .some((line) => {
+        const event = JSON.parse(line);
+        return event.session === name &&
+          event.type === "session_start" &&
+          typeof event.ts === "string" &&
+          event.ts >= createdAt;
+      });
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Bundled-context fallback: shell out to `pty run -d ...` on PATH.
  *
diff --git a/src/tui/interactive.ts b/src/tui/interactive.ts
index d00e338..7e79989 100644
--- a/src/tui/interactive.ts
+++ b/src/tui/interactive.ts
@@ -6,10 +6,10 @@ import { randomBytes } from "node:crypto";
 import { execFileSync, spawn as spawnChild, spawnSync } from "node:child_process";
 import { attach } from "../client.ts";
 import {
-  listSessions, acquireLock, releaseLock,
+  listSessions,
   cleanupAll, getSession, getSessionDir, type SessionInfo,
 } from "../sessions.ts";
-import { spawnDaemon } from "../spawn.ts";
+import { spawnDaemon, spawnDaemonWithCreationLock } from "../spawn.ts";
 import { matchesAllTags, isReservedTagKey } from "../tags.ts";
 import {
   app, screen, signal, computed, batch,
@@ -498,11 +498,13 @@ let myApp: ReturnType<typeof app> | null = null;
 async function doRestart(session: SessionInfo): Promise<void> {
   const meta = session.metadata;
   if (!meta) {
-    cleanupAll(session.name);
+    try {
+      cleanupAll(session.name);
+    } catch {}
     return;
   }
-  cleanupAll(session.name);
   try {
+    cleanupAll(session.name);
     // Preserve displayName (and tags) so a restarted session keeps its name
     // rather than reverting to its raw id.
     await spawnDaemon({
@@ -623,17 +625,6 @@ function doAttach(name: string): void {
 async function doCreate(dir: string, name: string, shell: string): Promise<void> {
   pauseApp();
 
-  // Random names come from randomSessionName() — no collision check needed,
-  // but we still acquireLock to guard against multi-process races during
-  // creation.
-  if (!acquireLock(name)) {
-    console.error(`Session "${name}" is being created by another process.`);
-    const updated = await listSessions();
-    sessions.set(updated);
-    resumeApp();
-    return;
-  }
-
   // Auto-apply --filter-tag tags so the new session stays in the layout.
   const tags = filterTags.peek();
   // displayName intentionally unset — matches `pty run --no-display-name`.
@@ -648,16 +639,19 @@ async function doCreate(dir: string, name: string, shell: string): Promise<void>
   };
 
   try {
-    await spawnDaemon(spawnOpts);
+    if (!await spawnDaemonWithCreationLock(spawnOpts)) {
+      console.error(`Session "${name}" is being created by another process.`);
+      const updated = await listSessions();
+      sessions.set(updated);
+      resumeApp();
+      return;
+    }
   } catch (e: any) {
-    releaseLock(name);
     console.error(e.message);
     const updated = await listSessions();
     sessions.set(updated);
     resumeApp();
     return;
-  } finally {
-    releaseLock(name);
   }
 
   doAttach(name);
diff --git a/tests/atomic-writes.test.ts b/tests/atomic-writes.test.ts
index b751a78..9586dde 100644
--- a/tests/atomic-writes.test.ts
+++ b/tests/atomic-writes.test.ts
@@ -19,9 +19,12 @@ import { spawn, spawnSync } from "node:child_process";
 import { terminateAndWait } from "./setup/processes.ts";
 import {
   atomicWriteFileSync, atomicWriteFile,
-  updateTags, readMetadata,
+  acquireLock, cleanupAll, releaseLock, updateTags, readMetadata,
 } from "../src/sessions.ts";
-import { appendEventSync, readRecentEvents } from "../src/events.ts";
+import {
+  acquireEventLock, appendEvent, appendEventSync, readRecentEvents, releaseEventLock,
+  waitForEventLock,
+} from "../src/events.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -203,6 +206,141 @@ describe("concurrent pty tag via multiple CLI processes", () => {
 });
 
 describe("event log truncation vs concurrent reader", () => {
+  it("cannot clean through a live metadata lock holder", () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    const metadataPath = path.join(dir, `${name}.json`);
+    const eventsPath = path.join(dir, `${name}.events.jsonl`);
+    fs.writeFileSync(metadataPath, JSON.stringify({ name }));
+    fs.writeFileSync(eventsPath, `${JSON.stringify({ type: "user.keep" })}\n`);
+    const metadataBefore = fs.readFileSync(metadataPath);
+    const eventsBefore = fs.readFileSync(eventsPath);
+    expect(acquireLock(name)).toBe(true);
+
+    try {
+      expect(() => cleanupAll(name)).toThrow(/metadata is busy/i);
+      expect(fs.readFileSync(metadataPath)).toEqual(metadataBefore);
+      expect(fs.readFileSync(eventsPath)).toEqual(eventsBefore);
+      expect(acquireLock(name)).toBe(false);
+    } finally {
+      releaseLock(name);
+    }
+
+    cleanupAll(name);
+    expect(fs.existsSync(metadataPath)).toBe(false);
+    expect(fs.existsSync(eventsPath)).toBe(false);
+  });
+
+  it("reclaims a stale event lock during full cleanup", () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    fs.writeFileSync(path.join(dir, `${name}.events.jsonl`), "");
+    fs.writeFileSync(path.join(dir, `${name}.events.lock`), "2147483647");
+
+    cleanupAll(name);
+
+    expect(fs.existsSync(path.join(dir, `${name}.events.jsonl`))).toBe(false);
+    expect(fs.existsSync(path.join(dir, `${name}.events.lock`))).toBe(false);
+  });
+
+  it("queues an async writer until the event lock is released", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireEventLock(name)).toBe(true);
+    const pending = appendEvent(name, {
+      session: name,
+      type: "user.queued",
+      ts: new Date().toISOString(),
+      data: { complete: true },
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(readRecentEvents(name)).toEqual([]);
+
+    releaseEventLock(name);
+    await pending;
+    expect(readRecentEvents(name)).toMatchObject([{
+      type: "user.queued",
+      data: { complete: true },
+    }]);
+  });
+
+  it("bounds async event-lock contention", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireEventLock(name)).toBe(true);
+
+    try {
+      await expect(waitForEventLock(name, 0)).rejects.toThrow(/event log is busy/i);
+    } finally {
+      releaseEventLock(name);
+    }
+  });
+
+  it("preserves concurrent records and an oversized metadata event across retention", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    const previousDescription = "😀".repeat(1000);
+    const nextDescription = "🫠".repeat(1000);
+    updateTags(name, { description: previousDescription });
+
+    const eventsPath = path.join(dir, `${name}.events.jsonl`);
+    const prime = Array.from({ length: 999 }, (_, i) => JSON.stringify({
+      session: name,
+      type: "user.prime",
+      ts: new Date().toISOString(),
+      data: { i },
+    })).join("\n") + "\n";
+    fs.writeFileSync(eventsPath, prime);
+
+    const markers = Array.from({ length: 16 }, (_, i) => `marker-${i}`);
+    const children = markers.map((marker) => spawn(nodeBin, [
+      cliPath, "emit", name, "user.concurrent", "--json", JSON.stringify({ marker }),
+    ], {
+      env: { ...process.env, PTY_SESSION_DIR: dir },
+      stdio: "ignore",
+    }));
+    const patchOnce = () => {
+      const child = spawn(nodeBin, [cliPath, "metadata", "patch", "--id", name], {
+        env: { ...process.env, PTY_SESSION_DIR: dir },
+        stdio: ["pipe", "ignore", "ignore"],
+      });
+      child.stdin!.end(JSON.stringify({ tags: { description: nextDescription } }));
+      return new Promise<number | null>((resolve) => child.once("exit", resolve));
+    };
+    const patchEventually = async () => {
+      for (let attempt = 0; attempt < 100; attempt++) {
+        if (await patchOnce() === 0) return;
+      }
+      throw new Error("metadata patch remained busy after concurrent writers completed");
+    };
+    const patchResult = patchEventually();
+    const statuses = await Promise.all(children.map((child) => new Promise<number | null>(
+      (resolve) => child.once("exit", resolve),
+    )));
+    expect(statuses).toEqual(Array(children.length).fill(0));
+    await patchResult;
+
+    const lines = fs.readFileSync(eventsPath, "utf8").trimEnd().split("\n");
+    const events = lines.map((line) => JSON.parse(line));
+    const observedMarkers = events
+      .filter((event) => event.type === "user.concurrent")
+      .map((event) => event.data.marker)
+      .sort();
+    expect(observedMarkers).toEqual([...markers].sort());
+    const metadataEvents = events.filter((event) => event.type === "metadata_change");
+    expect(metadataEvents).toHaveLength(1);
+    const metadataEvent = metadataEvents[0];
+    expect(metadataEvent.previous.tags.description).toBe(previousDescription);
+    expect(metadataEvent.value.tags.description).toBe(nextDescription);
+    expect(JSON.stringify(metadataEvent).length).toBeGreaterThan(4096);
+  }, 30_000);
+
   it("reader never sees a half-written file during truncation", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();
diff --git a/tests/display-name.test.ts b/tests/display-name.test.ts
index 4f74e0c..9c3480e 100644
--- a/tests/display-name.test.ts
+++ b/tests/display-name.test.ts
@@ -182,6 +182,33 @@ describe("--name: explicit display label (any length / chars)", () => {
     collectPid(dir, "a1");
     collectPid(dir, "a2");
   });
+
+  it.each([
+    ["leading whitespace", " Worker"],
+    ["trailing whitespace", "Worker "],
+    ["ASCII control", "Worker\u0007"],
+    ["Unicode line separator", "Worker\u2028Next"],
+    ["Unicode paragraph separator", "Worker\u2029Next"],
+    ["more than 160 Unicode scalars", "😀".repeat(161)],
+  ])("rejects %s before spawning", (_case, displayName) => {
+    const dir = makeSessionDir();
+    const id = `invalid-${Math.random().toString(36).slice(2, 8)}`;
+    const result = runCli(dir, {}, "run", "-d", "--id", id, "--name", displayName, "--", "cat");
+    if (result.status === 0) collectPid(dir, id);
+
+    expect(result.status).not.toBe(0);
+    expect(listJson(dir)).toEqual([]);
+  });
+
+  it("accepts 160 Unicode scalars plus slash and backslash as pure metadata", () => {
+    const dir = makeSessionDir();
+    const displayName = `${"😀".repeat(156)}/a\\b`;
+    const result = runCli(dir, {}, "run", "-d", "--id", "unicode-boundary", "--name", displayName, "--", "cat");
+
+    expect(result.status).toBe(0);
+    expect(listJson(dir).find((session: any) => session.name === "unicode-boundary")?.displayName).toBe(displayName);
+    collectPid(dir, "unicode-boundary");
+  });
 });
 
 describe("pty rename (outside a session)", () => {
diff --git a/tests/gc-parent-child.test.ts b/tests/gc-parent-child.test.ts
index e1edc7d..e2924d3 100644
--- a/tests/gc-parent-child.test.ts
+++ b/tests/gc-parent-child.test.ts
@@ -5,6 +5,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
+import { acquireLock, gc, releaseLock } from "../src/sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -88,6 +89,28 @@ afterEach(async () => {
 });
 
 describe("pty gc — parent-child orphan-kill", () => {
+  it("continues the batch without reporting a cleanup blocked by a live lock", async () => {
+    const dir = makeSessionDir();
+    const blocked = uniqueName("blocked");
+    const removable = uniqueName("removable");
+    await startDaemon(dir, blocked, "cat", [], { parent: "missing-parent" });
+    await startDaemon(dir, removable, "cat", [], { parent: "missing-parent" });
+    const previousRoot = process.env.PTY_SESSION_DIR;
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireLock(blocked)).toBe(true);
+
+    try {
+      const result = await gc();
+      expect(result.killedOrphanChildren.map(({ name }) => name)).toEqual([removable]);
+      expect(fs.existsSync(path.join(dir, `${blocked}.json`))).toBe(true);
+      expect(fs.existsSync(path.join(dir, `${removable}.json`))).toBe(false);
+    } finally {
+      releaseLock(blocked);
+      if (previousRoot === undefined) delete process.env.PTY_SESSION_DIR;
+      else process.env.PTY_SESSION_DIR = previousRoot;
+    }
+  }, 15000);
+
   it("kills a child when its parent's daemon is dead (no exit record)", async () => {
     const dir = makeSessionDir();
     const parent = uniqueName("par");
diff --git a/tests/metadata-events.test.ts b/tests/metadata-events.test.ts
index c0df4e8..7aa570a 100644
--- a/tests/metadata-events.test.ts
+++ b/tests/metadata-events.test.ts
@@ -8,12 +8,18 @@ import { terminateAndWait } from "./setup/processes.ts";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as net from "node:net";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import {
-  patchMetadataById, setDisplayName, updateTags, readMetadata,
+  acquireLock, patchMetadataById, readMetadata, releaseLock, setDisplayName,
+  updateTags, writeMetadata,
 } from "../src/sessions.ts";
-import { EventFollower, formatEvent, type EventRecord } from "../src/events.ts";
+import {
+  acquireEventLock, EventFollower, formatEvent, releaseEventLock,
+  type EventRecord,
+} from "../src/events.ts";
+import { encodeAttach } from "../src/protocol.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -39,10 +45,15 @@ function uniqueName(): string {
   return `mev${++nameCounter}-${Math.random().toString(36).slice(2, 6)}`;
 }
 
-async function startDaemon(sessionDir: string, name: string): Promise<number> {
+async function startDaemon(
+  sessionDir: string,
+  name: string,
+  overrides: Record<string, unknown> = {},
+): Promise<number> {
   const config = JSON.stringify({
     name, command: "cat", args: [], displayCommand: "cat",
     cwd: os.tmpdir(), rows: 24, cols: 80,
+    ...overrides,
   });
   const child = spawn(nodeBin, [serverModule], {
     detached: true,
@@ -70,6 +81,32 @@ async function startDaemon(sessionDir: string, name: string): Promise<number> {
   throw new Error("Timeout waiting for daemon");
 }
 
+async function attach(sessionDir: string, name: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const socket = net.createConnection(path.join(sessionDir, `${name}.sock`), () => {
+      socket.write(encodeAttach(24, 80));
+    });
+    socket.once("data", () => {
+      socket.destroy();
+      resolve();
+    });
+    socket.once("error", reject);
+  });
+}
+
+async function waitFor(
+  predicate: () => boolean,
+  description: string,
+  timeoutMs = 3_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  throw new Error(`Timed out waiting for ${description}`);
+}
+
 function runCli(sessionDir: string, env: Record<string, string>, ...args: string[]) {
   return spawnSync(nodeBin, [cliPath, ...args], {
     env: { ...process.env, PTY_SESSION_DIR: sessionDir, ...env },
@@ -106,6 +143,123 @@ function readEvents(dir: string, name: string): any[] {
 }
 
 describe("patchMetadataById", () => {
+  it("fails before changing metadata or events when event publication is locked", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    const metadataPath = path.join(dir, `${name}.json`);
+    const eventsPath = path.join(dir, `${name}.events.jsonl`);
+    const metadataBefore = fs.readFileSync(metadataPath);
+    const eventsBefore = fs.readFileSync(eventsPath);
+    expect(acquireEventLock(name)).toBe(true);
+
+    try {
+      await expect(patchMetadataById(name, {
+        displayName: "Blocked",
+        tags: { description: "x".repeat(1000) },
+      })).rejects.toThrow(/event log is busy/i);
+      expect(fs.readFileSync(metadataPath)).toEqual(metadataBefore);
+      expect(fs.readFileSync(eventsPath)).toEqual(eventsBefore);
+    } finally {
+      releaseEventLock(name);
+    }
+  }, 15_000);
+
+  it("preserves the complete recovery record and unknown future fields", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    const current = readMetadata(name)!;
+    writeMetadata(name, {
+      ...current,
+      rows: 41,
+      cols: 121,
+      ephemeral: true,
+      isolateEnv: true,
+      extraEnv: { ASSIGNED: "yes" },
+      unsetEnv: ["NO_COLOR"],
+      futureRecoveryCapability: { version: 2 },
+    } as typeof current);
+
+    const result = await patchMetadataById(name, {
+      displayName: "Recovery-safe",
+      tags: { owner: "agent" },
+    });
+
+    expect(result.metadata).toMatchObject({
+      rows: 41,
+      cols: 121,
+      ephemeral: true,
+      isolateEnv: true,
+      extraEnv: { ASSIGNED: "yes" },
+      unsetEnv: ["NO_COLOR"],
+      futureRecoveryCapability: { version: 2 },
+      displayName: "Recovery-safe",
+      tags: { owner: "agent" },
+    });
+  }, 15_000);
+
+  it("daemon attach cannot write through a held metadata lock", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    await patchMetadataById(name, { displayName: "Locked", tags: { owner: "agent" } });
+    const before = fs.readFileSync(path.join(dir, `${name}.json`), "utf8");
+    expect(acquireLock(name)).toBe(true);
+
+    try {
+      await attach(dir, name);
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(fs.readFileSync(path.join(dir, `${name}.json`), "utf8")).toBe(before);
+    } finally {
+      releaseLock(name);
+    }
+
+    await attach(dir, name);
+    await waitFor(() => readMetadata(name)?.lastAttachAt !== undefined, "post-lock attach metadata");
+    expect(readMetadata(name)).toMatchObject({
+      displayName: "Locked",
+      tags: { owner: "agent" },
+    });
+  }, 15_000);
+
+  it("exit metadata retries after a short external lock winner", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name, {
+      command: "sh",
+      args: ["-c", "sleep 0.4; exit 7"],
+      displayCommand: "exit 7",
+      tags: { keep: "true" },
+      unsetEnv: ["NO_COLOR"],
+    });
+    process.env.PTY_SESSION_DIR = dir;
+    await patchMetadataById(name, { displayName: "Exiting", tags: { owner: "agent" } });
+    expect(acquireLock(name)).toBe(true);
+
+    try {
+      await waitFor(
+        () => readEvents(dir, name).some((event) => event.type === "session_exit"),
+        "session_exit while metadata is locked",
+      );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(readMetadata(name)?.exitedAt).toBeUndefined();
+    } finally {
+      releaseLock(name);
+    }
+
+    await waitFor(() => readMetadata(name)?.exitedAt !== undefined, "close-time exit metadata flush");
+    expect(readMetadata(name)).toMatchObject({
+      exitCode: 7,
+      displayName: "Exiting",
+      tags: { keep: "true", owner: "agent" },
+      unsetEnv: ["NO_COLOR"],
+    });
+  }, 15_000);
+
   it("atomically changes displayName and tags while preserving unrelated tags", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();
@@ -183,7 +337,10 @@ describe("patchMetadataById", () => {
   }, 15000);
 
   it.each([
-    [{ displayName: "bad/name" }, /Invalid displayName/],
+    [{ displayName: " Worker" }, /Invalid displayName/],
+    [{ displayName: "Worker\u2028Next" }, /Invalid displayName/],
+    [{ displayName: "Worker\u2029Next" }, /Invalid displayName/],
+    [{ displayName: "😀".repeat(161) }, /Invalid displayName/],
     [{ tags: { "": "value" } }, /tag keys must be non-empty/],
     [{ tags: { role: 1 } }, /tag values must be strings or null/],
     [{ unknown: true }, /unknown field "unknown"/],
@@ -199,6 +356,18 @@ describe("patchMetadataById", () => {
     expect(readEvents(dir, name).filter((event) => event.type === "metadata_change")).toHaveLength(0);
   }, 15000);
 
+  it("accepts the 160-scalar boundary with slash and backslash", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name);
+    process.env.PTY_SESSION_DIR = dir;
+    const displayName = `${"😀".repeat(156)}/a\\b`;
+
+    const result = await patchMetadataById(name, { displayName });
+
+    expect(result.metadata.displayName).toBe(displayName);
+  }, 15000);
+
   it("exposes the exact-id atomic operation through JSON stdin/stdout", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();
diff --git a/tests/spawn-options.test.ts b/tests/spawn-options.test.ts
index 90868ce..fc86494 100644
--- a/tests/spawn-options.test.ts
+++ b/tests/spawn-options.test.ts
@@ -6,7 +6,12 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { queryStats } from "../src/client.ts";
-import { spawnDaemon, setServerModulePath } from "../src/spawn.ts";
+import {
+  spawnDaemon, spawnDaemonWithCreationLock, setServerModulePath,
+} from "../src/spawn.ts";
+import {
+  acquireLock, patchMetadataById, releaseLock,
+} from "../src/sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -144,6 +149,103 @@ afterEach(async () => {
 });
 
 describe("spawnDaemon options", () => {
+  it("releases a failed owned creation lease exactly once", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+
+    const failedSpawn = spawnDaemonWithCreationLock({
+      name,
+      command: "cat",
+      args: [],
+      displayCommand: "cat",
+      launcher: { command: nodeBin, args: ["-e", "process.exit(7)"] },
+      startTimeoutMs: 300,
+    });
+    const competitor = (async () => {
+      while (!acquireLock(name)) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+      }
+      return fs.statSync(path.join(dir, `${name}.lock`)).ino;
+    })();
+
+    await expect(failedSpawn).rejects.toThrow();
+    const competitorLockInode = await competitor;
+    try {
+      await new Promise((resolve) => setImmediate(resolve));
+      expect(acquireLock(name)).toBe(false);
+      expect(fs.statSync(path.join(dir, `${name}.lock`)).ino).toBe(competitorLockInode);
+    } finally {
+      releaseLock(name);
+    }
+  }, 5000);
+
+  it("validates displayName before launching the daemon", async () => {
+    const dir = makeSessionDir();
+    process.env.PTY_SESSION_DIR = dir;
+
+    await expect(spawnDaemon({
+      name: uniqueName(),
+      command: "cat",
+      args: [],
+      displayCommand: "cat",
+      displayName: " Worker",
+    })).rejects.toThrow("Display name must be trimmed");
+    expect(fs.readdirSync(dir)).toEqual([]);
+  });
+
+  it("does not report readiness for a socket without matching daemon metadata", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    const socketOnlyLauncher = [
+      'const net = require("node:net")',
+      'const path = require("node:path")',
+      'const name = JSON.parse(process.env.PTY_SERVER_CONFIG).name',
+      'net.createServer(() => {}).listen(path.join(process.env.PTY_SESSION_DIR, `${name}.sock`))',
+      'setInterval(() => {}, 1000)',
+    ].join(";");
+
+    await expect(spawnDaemon({
+      name,
+      command: "cat",
+      args: [],
+      displayCommand: "cat",
+      launcher: { command: nodeBin, args: ["-e", socketOnlyLauncher] },
+      startTimeoutMs: 300,
+    })).rejects.toThrow("daemon publication");
+    expect(fs.existsSync(path.join(dir, `${name}.json`))).toBe(false);
+  }, 5000);
+
+  it("returns only after the fresh session_start is published", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    fs.writeFileSync(path.join(dir, `${name}.events.jsonl`), JSON.stringify({
+      session: name,
+      type: "session_start",
+      ts: "9999-12-31T23:59:59.999Z",
+    }) + "\n");
+
+    await spawnDaemon({
+      name,
+      command: "cat",
+      args: [],
+      displayCommand: "cat",
+    });
+    await patchMetadataById(name, { displayName: "Ready" });
+
+    const events = fs.readFileSync(path.join(dir, `${name}.events.jsonl`), "utf8")
+      .trimEnd().split("\n").map((line) => JSON.parse(line));
+    expect(events.map(({ type }) => type).slice(0, 2)).toEqual([
+      "session_start",
+      "metadata_change",
+    ]);
+    expect(events[0].ts).not.toBe("9999-12-31T23:59:59.999Z");
+    const pid = parseInt(fs.readFileSync(path.join(dir, `${name}.pid`), "utf8"), 10);
+    bgPids.push(pid);
+  }, 15000);
+
   it("CLI passes through to spawnDaemon with options object", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();
@@ -169,6 +271,32 @@ describe("spawnDaemon options", () => {
     bgPids.push(pid);
   }, 15000);
 
+  it("preserves an explicitly delegated creation lock through publication", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireLock(name)).toBe(true);
+
+    try {
+      const result = spawnSync(nodeBin, [cliPath, "run", "-d", "--id", name, "--", "cat"], {
+        env: {
+          ...process.env,
+          PTY_SESSION_DIR: dir,
+          PTY_CREATION_LOCK_OWNER_PID: String(process.pid),
+        },
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+
+      expect(result.status).toBe(0);
+      expect(fs.readFileSync(path.join(dir, `${name}.lock`), "utf8").trim()).toBe(String(process.pid));
+      const pid = parseInt(fs.readFileSync(path.join(dir, `${name}.pid`), "utf-8").trim(), 10);
+      bgPids.push(pid);
+    } finally {
+      releaseLock(name);
+    }
+  }, 15000);
+
   it("custom rows and cols are applied via server config", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();

From 0deb3f0ad6eb07f30ad9dea6392b843d4495ad5f Mon Sep 17 00:00:00 2001
From: schickling-assistant
 <261620128+schickling-assistant@users.noreply.github.com>
Date: Fri, 31 Jul 2026 18:33:43 +0200
Subject: [PATCH 3/3] fix: serialize GC and exec lifecycle mutations

---
 CHANGELOG.md                      |   3 +
 src/cli.ts                        |  80 +++++++----
 src/server.ts                     |  14 +-
 src/sessions.ts                   | 232 ++++++++++++++++++++++--------
 tests/exec.test.ts                |  96 ++++++++++++-
 tests/gc-abandoned.test.ts        |  31 ++++
 tests/gc-generation-guard.test.ts |  48 +++++++
 tests/gc-parent-child.test.ts     |  11 +-
 tests/spawn-options.test.ts       |   3 +-
 9 files changed, 420 insertions(+), 98 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 134f942..cc7f5ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,9 @@
 - Metadata publication acquires the event lock before the metadata lock, so a
   busy event log fails before either file changes. Event appends and retention
   rewrites are serialized without a per-record byte-size assumption.
+- `pty exec` now carries an opaque generation owner token in session children
+  and refuses stale same-id replacements. Sessions started by an older build
+  must be restarted once before they can use `pty exec`.
 - The current display-name contract supersedes the permissive limits described
   in earlier release notes: values must be nonempty, already trimmed,
   single-line, free of Unicode control characters, and at most 160 Unicode
diff --git a/src/cli.ts b/src/cli.ts
index 07dd83e..68df3f3 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -27,6 +27,7 @@ import {
   updateTags,
   setDisplayName,
   patchMetadataById,
+  mutateMetadataUnderLock,
   allSessionNames,
   readMetadata,
   readSessionPid,
@@ -39,7 +40,7 @@ import {
 } from "./sessions.ts";
 import { spawnDaemon, resolveCommand } from "./spawn.ts";
 import {
-  acquireEventLock, EventFollower, EventWriter, EventType, releaseEventLock,
+  acquireEventLock, appendEventSyncLocked, EventFollower, EventWriter, EventType, releaseEventLock,
   readRecentEvents, formatEvent,
   emitUserEvent,
 } from "./events.ts";
@@ -1778,6 +1779,12 @@ async function cmdExec(command: string, cmdArgs: string[]): Promise<void> {
     console.error("pty exec: not inside a pty session (PTY_SESSION not set).");
     process.exit(1);
   }
+  const ownerGeneration = process.env.PTY_SESSION_GENERATION;
+  if (!ownerGeneration) {
+    throw new Error(
+      "pty exec: current session has no generation owner token; restart it before using pty exec.",
+    );
+  }
 
   const meta = readMetadata(sessionName);
   if (!meta) {
@@ -1785,12 +1792,6 @@ async function cmdExec(command: string, cmdArgs: string[]): Promise<void> {
     process.exit(1);
   }
 
-  if (meta.tags?.ptyfile) {
-    console.error(`pty exec: session "${sessionName}" is managed by ${meta.tags.ptyfile}`);
-    console.error("Edit the pty.toml to change the command instead.");
-    process.exit(1);
-  }
-
   // Resolve the command to an absolute path
   let resolved: string;
   try {
@@ -1800,26 +1801,45 @@ async function cmdExec(command: string, cmdArgs: string[]): Promise<void> {
     process.exit(1);
   }
 
-  // Update metadata with the new command
-  const previousCommand = meta.displayCommand ?? [meta.command, ...(meta.args ?? [])].join(" ");
   const displayCommand = [command, ...cmdArgs].join(" ");
-  writeMetadata(sessionName, {
-    ...meta,
-    command: resolved,
-    args: cmdArgs,
-    displayCommand,
-  });
+  if (!acquireEventLock(sessionName)) {
+    throw new Error(`pty exec: session "${sessionName}" event log is busy; retry the operation.`);
+  }
+  try {
+    let previousCommand = "";
+    const result = mutateMetadataUnderLock(sessionName, (current) => {
+      if (current.tags?.ptyfile) {
+        throw new Error(
+          `pty exec: session "${sessionName}" is managed by ${current.tags.ptyfile}. ` +
+          "Edit the pty.toml to change the command instead.",
+        );
+      }
+      previousCommand = current.displayCommand ??
+        [current.command, ...(current.args ?? [])].join(" ");
+      current.command = resolved;
+      current.args = cmdArgs;
+      current.displayCommand = displayCommand;
+      return true;
+    }, {
+      expectedGeneration: ownerGeneration,
+      onPublished: () => appendEventSyncLocked(sessionName, {
+        session: sessionName,
+        type: EventType.SESSION_EXEC,
+        ts: new Date().toISOString(),
+        previousCommand,
+        command: displayCommand,
+      }),
+    });
 
-  // Emit exec event
-  const writer = new EventWriter(sessionName);
-  writer.append({
-    session: sessionName,
-    type: EventType.SESSION_EXEC,
-    ts: new Date().toISOString(),
-    previousCommand,
-    command: displayCommand,
-  } as any);
-  await writer.flush();
+    if (result.status !== "changed") {
+      const reason = result.status === "generation-mismatch"
+        ? "belongs to a replacement generation"
+        : `could not be updated (${result.status})`;
+      throw new Error(`pty exec: session "${sessionName}" ${reason}; command was not run.`);
+    }
+  } finally {
+    releaseEventLock(sessionName);
+  }
 
   // Replace this process with the new command
   const result = spawnSync(resolved, cmdArgs, {
@@ -2806,6 +2826,12 @@ async function cmdGc(
       : a.reason;
     console.log(`${abandonVerb}: ${a.name} (${detail})`);
   }
+  for (const skipped of result.reapSkipped) {
+    const phase = skipped.signalled ? "after signalling" : "before signalling";
+    console.log(
+      `Skipped ${skipped.operation} reap: ${skipped.name} (${skipped.reason}, ${phase})`,
+    );
+  }
   for (const r of result.respawned) {
     const note = r.ptyfileReread ? " (pty.toml re-read)" : "";
     console.log(`${respawnVerb}: ${r.name}${note}`);
@@ -2842,6 +2868,7 @@ async function cmdGc(
   const totalActions =
     result.killedOrphanChildren.length +
     result.abandoned.length +
+    result.reapSkipped.length +
     result.respawned.length +
     result.respawnFailed.length +
     result.flapped.length +
@@ -2861,6 +2888,9 @@ async function cmdGc(
   if (result.abandoned.length > 0) {
     parts.push(`${result.abandoned.length} abandoned`);
   }
+  if (result.reapSkipped.length > 0) {
+    parts.push(`${result.reapSkipped.length} reap skip${result.reapSkipped.length === 1 ? "" : "s"}`);
+  }
   if (result.respawned.length > 0) {
     parts.push(`${result.respawned.length} respawn${result.respawned.length === 1 ? "" : "s"}`);
   }
diff --git a/src/server.ts b/src/server.ts
index 4bde720..6761300 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -81,8 +81,9 @@ export interface ServerOptions {
    *  before `extraEnv`, so an explicit assignment wins when both mention a key. */
   unsetEnv?: string[];
   /** Use this env dict verbatim for the spawned child — no inheritance from
-   *  the daemon's `process.env`, no allow-list. `PTY_SESSION` is always
-   *  injected on top so nesting detection and `pty exec` keep working.
+   *  the daemon's `process.env`, no allow-list. `PTY_SESSION` and the opaque
+   *  `PTY_SESSION_GENERATION` owner token are always injected on top so
+   *  nesting detection and generation-safe `pty exec` keep working.
    *
    *  Mutually exclusive with `isolateEnv` / `extraEnv` / `unsetEnv` — passing
    *  `env` together with inherited-environment policy throws. Use this when
@@ -130,11 +131,12 @@ function buildChildEnv(options: ServerOptions): Record<string, string> {
     );
   }
 
-  // Explicit verbatim env. No inheritance. Only PTY_SESSION is forced on
-  // top so internal pty tooling (nesting prevention, `pty exec`) works.
+  // Explicit verbatim env. No inheritance. PTY's identity and owner token are
+  // forced on top so internal tooling can fail closed across same-id reuse.
   if (options.env) {
     const env = { ...options.env };
     env.PTY_SESSION = options.name;
+    if (options.generation) env.PTY_SESSION_GENERATION = options.generation;
     ensureChildTerm(env);
     return env;
   }
@@ -150,6 +152,7 @@ function buildChildEnv(options: ServerOptions): Record<string, string> {
       for (const [k, v] of Object.entries(options.extraEnv)) env[k] = v;
     }
     env.PTY_SESSION = options.name;
+    if (options.generation) env.PTY_SESSION_GENERATION = options.generation;
     ensureChildTerm(env);
     return env;
   }
@@ -164,6 +167,7 @@ function buildChildEnv(options: ServerOptions): Record<string, string> {
     for (const [k, v] of Object.entries(options.extraEnv)) env[k] = v;
   }
   env.PTY_SESSION = options.name;
+  if (options.generation) env.PTY_SESSION_GENERATION = options.generation;
   ensureChildTerm(env);
   return env;
 }
@@ -475,7 +479,7 @@ export class PtyServer {
     // Spawn the child process in a PTY via a shell, so that shell scripts,
     // symlinks, and shebangs all work reliably (like tmux/screen do).
     // `exec "$@"` replaces the shell with the actual process.
-    const childEnv = buildChildEnv(options);
+    const childEnv = buildChildEnv({ ...options, generation: this.generation });
 
     const invalidCwd = describeInvalidCwd(options.cwd);
     if (invalidCwd !== undefined) {
diff --git a/src/sessions.ts b/src/sessions.ts
index 83ff484..16d5689 100644
--- a/src/sessions.ts
+++ b/src/sessions.ts
@@ -4,11 +4,13 @@ import * as path from "node:path";
 import * as os from "node:os";
 import * as net from "node:net";
 import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
 // Circular import: events.ts imports getEventsPath/ensureSessionDir from
 // this file. Cycle is safe — `appendEventSync` is only called at runtime
 // from inside functions, never at module-init time.
 import {
   acquireEventLock, appendEventSync, appendEventSyncLocked, releaseEventLock,
+  type EventRecord,
 } from "./events.ts";
 
 export const DEFAULT_SESSION_DIR = path.join(os.homedir(), ".local", "state", "pty");
@@ -267,6 +269,7 @@ export function mutateMetadataUnderLock(
   mutate: (metadata: SessionMetadata) => boolean,
   options: {
     expectedGeneration?: string;
+    expectedMetadata?: SessionMetadata;
     onPublished?: (metadata: SessionMetadata) => void;
   } = {},
 ): MetadataMutationResult {
@@ -275,6 +278,12 @@ export function mutateMetadataUnderLock(
   try {
     const metadata = readMetadata(name);
     if (!metadata) return { status: "missing" };
+    if (
+      options.expectedMetadata !== undefined &&
+      !metadataMatchesObservation(options.expectedMetadata, metadata)
+    ) {
+      return { status: "generation-mismatch" };
+    }
     if (
       options.expectedGeneration !== undefined &&
       metadata.generation !== options.expectedGeneration
@@ -287,6 +296,12 @@ export function mutateMetadataUnderLock(
 
     const latest = readMetadata(name);
     if (!latest || JSON.stringify(latest) !== observed) return { status: "stale" };
+    if (
+      options.expectedMetadata !== undefined &&
+      !metadataMatchesObservation(options.expectedMetadata, latest)
+    ) {
+      return { status: "generation-mismatch" };
+    }
     if (
       options.expectedGeneration !== undefined &&
       latest.generation !== options.expectedGeneration
@@ -689,6 +704,102 @@ export async function cleanupObservedSession(
   }
 }
 
+type ReapObservedResult =
+  | { status: "reaped" }
+  | {
+    status: "skipped";
+    reason: "busy" | "stale" | "signal-failed" | "shutdown-timeout";
+    signalled: boolean;
+  };
+
+function hasProcessExitedForReap(pid: number): boolean {
+  if (!isProcessAlive(pid)) return true;
+  try {
+    if (process.platform === "linux") {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+      const stateOffset = stat.lastIndexOf(") ") + 2;
+      return stateOffset >= 2 && stat[stateOffset] === "Z";
+    }
+    const state = execFileSync("ps", ["-o", "stat=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 1000,
+    }).trim();
+    return state === "" || state.startsWith("Z");
+  } catch {
+    return !isProcessAlive(pid);
+  }
+}
+
+/** Signal only after proving ownership, then reacquire after daemon shutdown
+ *  so its final event/metadata flush cannot recreate artifacts after cleanup. */
+async function reapObservedSession(
+  session: SessionInfo,
+  event?: Extract<EventRecord, { type: "session_abandoned" }>,
+): Promise<ReapObservedResult> {
+  if (!session.metadata) return { status: "skipped", reason: "stale", signalled: false };
+  if (!acquireEventLock(session.name)) {
+    return { status: "skipped", reason: "busy", signalled: false };
+  }
+  if (!acquireLock(session.name)) {
+    releaseEventLock(session.name);
+    return { status: "skipped", reason: "busy", signalled: false };
+  }
+  let signalled = false;
+  let signalFailed = false;
+  try {
+    const current = readMetadata(session.name);
+    if (!current || !metadataMatchesObservation(session.metadata, current)) {
+      return { status: "skipped", reason: "stale", signalled: false };
+    }
+
+    if (session.status === "running" && session.pid != null) {
+      try {
+        process.kill(session.pid, "SIGTERM");
+        signalled = true;
+      } catch {
+        signalFailed = isProcessAlive(session.pid);
+      }
+    }
+  } finally {
+    releaseLock(session.name);
+    releaseEventLock(session.name);
+  }
+
+  if (signalFailed) {
+    return { status: "skipped", reason: "signal-failed", signalled: false };
+  }
+
+  if (signalled && session.pid != null) {
+    const deadline = Date.now() + 7000;
+    while (Date.now() < deadline && !hasProcessExitedForReap(session.pid)) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (!hasProcessExitedForReap(session.pid)) {
+      return { status: "skipped", reason: "shutdown-timeout", signalled: true };
+    }
+  }
+
+  if (!acquireEventLock(session.name)) {
+    return { status: "skipped", reason: "busy", signalled };
+  }
+  if (!acquireLock(session.name)) {
+    releaseEventLock(session.name);
+    return { status: "skipped", reason: "busy", signalled };
+  }
+  try {
+    const current = readMetadata(session.name);
+    if (!current || !metadataMatchesObservation(session.metadata, current)) {
+      return { status: "skipped", reason: "stale", signalled };
+    }
+    if (event) appendEventSyncLocked(session.name, event);
+    cleanupAllWhileLocked(session.name);
+    return { status: "reaped" };
+  } finally {
+    releaseLock(session.name);
+    releaseEventLock(session.name);
+  }
+}
+
 /** Return one bounded, read-only observation of the session registry.
  *
  * This function deliberately performs no lifecycle work: it does not create
@@ -949,6 +1060,14 @@ export interface GcResult {
    *  `idleDays` threshold is set (via CLI flag or per-session tag)
    *  and `lastAttachAt` is older than that threshold. */
   abandoned: { name: string; reason: "cwd-gone" | "idle"; idleDays?: number }[];
+  /** Reaps that could not complete safely. `signalled` distinguishes initial
+   *  contention (the process was untouched) from a race after shutdown began. */
+  reapSkipped: {
+    name: string;
+    operation: "orphan" | "abandoned";
+    reason: "busy" | "stale" | "signal-failed" | "shutdown-timeout";
+    signalled: boolean;
+  }[];
   /** Permanent sessions respawned this pass. `ptyfileReread` indicates
    *  whether the spawn used a fresh `pty.toml` read (when the session
    *  carries `ptyfile` + `ptyfile.session` tags) or its stored metadata. */
@@ -984,6 +1103,35 @@ export const DEFAULT_FAST_FAIL_WINDOW_SEC = 60;
  *  per-session `strategy.fast-fail-limit` tag. */
 export const DEFAULT_FAST_FAIL_LIMIT = 3;
 
+/** @internal Commit one gc flapping transition against the observed generation. */
+export function commitObservedFlapping(
+  name: string,
+  observed: SessionMetadata,
+  bookkeeping: Record<string, string>,
+  event: { counter: number; limit: number; window: number },
+): boolean {
+  if (!acquireEventLock(name)) return false;
+  try {
+    const result = mutateMetadataUnderLock(name, (metadata) => {
+      metadata.tags = { ...(metadata.tags ?? {}), ...bookkeeping };
+      return true;
+    }, {
+      expectedMetadata: observed,
+      onPublished: () => appendEventSyncLocked(name, {
+        session: name,
+        type: "session_flapping",
+        ts: new Date().toISOString(),
+        counter: event.counter,
+        limit: event.limit,
+        window: event.window,
+      }),
+    });
+    return result.status === "changed";
+  } finally {
+    releaseEventLock(name);
+  }
+}
+
 /** SHA-256 of a session's respawn command line, used to auto-reset the
  *  fast-fail counter when the operator edits the pty.toml (or otherwise
  *  changes the stored command). Kept short — the tag surface is user-
@@ -1072,6 +1220,7 @@ export async function gc(
   // loser dies; on the next tick the winner has no live parent either
   // and dies too. No cycle detection needed.
   const killedOrphanChildren: GcResult["killedOrphanChildren"] = [];
+  const reapSkipped: GcResult["reapSkipped"] = [];
   const withParent = initial
     .filter((s) => s.metadata?.tags?.parent)
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -1083,22 +1232,14 @@ export async function gc(
     if (parentAlive) continue;
     const reason: "missing" | "dead" = parentMeta ? "dead" : "missing";
     if (!dryRun) {
-      if (s.status === "running" && s.pid != null) {
-        // SIGTERM the live daemon, then wait briefly for it to exit so
-        // its shutdown handler doesn't race our cleanupAll by writing
-        // metadata back to disk after we've removed it. We poll the
-        // pid (up to ~1s) and fall through whether or not the daemon
-        // shut down in time — cleanupAll wipes whatever remains.
-        try { process.kill(s.pid, "SIGTERM"); } catch {}
-        const deadline = Date.now() + 1000;
-        while (Date.now() < deadline) {
-          if (!isProcessAlive(s.pid)) break;
-          await new Promise((r) => setTimeout(r, 25));
-        }
-      }
-      try {
-        cleanupAll(s.name);
-      } catch {
+      const result = await reapObservedSession(s);
+      if (result.status === "skipped") {
+        reapSkipped.push({
+          name: s.name,
+          operation: "orphan",
+          reason: result.reason,
+          signalled: result.signalled,
+        });
         continue;
       }
     }
@@ -1117,30 +1258,20 @@ export async function gc(
     if (!decision) continue;
 
     if (!dryRun) {
-      if (s.status === "running" && s.pid != null) {
-        try { process.kill(s.pid, "SIGTERM"); } catch {}
-        const deadline = Date.now() + 1000;
-        while (Date.now() < deadline) {
-          if (!isProcessAlive(s.pid)) break;
-          await new Promise((r) => setTimeout(r, 25));
-        }
-      }
-      // Emit the abandoned event BEFORE cleanupAll — cleanupAll unlinks
-      // the events file, and appendEventSync into a nonexistent file
-      // would just create a stub with a single event and leave orphaned
-      // JSONL on disk. Ordering: event → cleanup → gone.
-      try {
-        appendEventSync(s.name, {
+      const result = await reapObservedSession(s, {
           session: s.name,
           type: "session_abandoned",
           ts: new Date().toISOString(),
           reason: decision.reason,
           ...(decision.idleDays !== undefined ? { idleDays: decision.idleDays } : {}),
+      });
+      if (result.status === "skipped") {
+        reapSkipped.push({
+          name: s.name,
+          operation: "abandoned",
+          reason: result.reason,
+          signalled: result.signalled,
         });
-      } catch {}
-      try {
-        cleanupAll(s.name);
-      } catch {
         continue;
       }
     }
@@ -1197,34 +1328,16 @@ export async function gc(
     }
 
     if (decision.action === "flap-now") {
-      // Persist the flapping mark to on-disk metadata so subsequent
-      // ticks see it. We update the metadata file directly instead of
-      // going through updateTags — the session's daemon is gone, there's
-      // no live connection to notify, and cleanupAll ordering constraints
-      // in respawnPermanent don't apply here (we're NOT respawning).
-      try {
-        const meta = readMetadata(s.name);
-        if (meta) {
-          const merged: Record<string, string> = {
-            ...(meta.tags ?? {}),
-            ...decision.newBookkeeping,
-          };
-          writeMetadata(s.name, { ...meta, tags: merged });
-        }
-      } catch {
-        // Best-effort — if we can't persist the flag now, the next tick
-        // will recompute the same decision and try again.
-      }
-      try {
-        appendEventSync(s.name, {
-          session: s.name,
-          type: "session_flapping",
-          ts: new Date().toISOString(),
+      if (!commitObservedFlapping(
+        s.name,
+        s.metadata!,
+        decision.newBookkeeping,
+        {
           counter: decision.counter,
           limit: decision.effectiveLimit,
           window: decision.effectiveWindow,
-        });
-      } catch {}
+        },
+      )) continue;
       flapped.push({
         name: s.name,
         counter: decision.counter,
@@ -1274,6 +1387,7 @@ export async function gc(
     kept,
     killedOrphanChildren,
     abandoned,
+    reapSkipped,
     respawned,
     respawnFailed,
     flapped,
diff --git a/tests/exec.test.ts b/tests/exec.test.ts
index 6c10254..991e5d0 100644
--- a/tests/exec.test.ts
+++ b/tests/exec.test.ts
@@ -6,6 +6,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { readRecentEvents } from "../src/events.ts";
+import { acquireLock, releaseLock } from "../src/sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -75,6 +76,27 @@ function readMeta(sessionDir: string, name: string): any {
   } catch { return null; }
 }
 
+function readEvents(sessionDir: string, name: string): any[] {
+  try {
+    return fs.readFileSync(path.join(sessionDir, `${name}.events.jsonl`), "utf-8")
+      .trimEnd()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function execEnv(sessionDir: string, name: string, generation?: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    PTY_SESSION_DIR: sessionDir,
+    PTY_SESSION: name,
+    PTY_SESSION_GENERATION: generation ?? readMeta(sessionDir, name).generation,
+  };
+}
+
 afterEach(async () => {
   await terminateAndWait(bgPids);
   bgPids = [];
@@ -94,7 +116,7 @@ describe("pty exec", () => {
 
     // Run pty exec inside the session (simulate via PTY_SESSION env var)
     const result = spawnSync(nodeBin, [cliPath, "exec", "--", "echo", "hello-from-exec"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -132,7 +154,7 @@ describe("pty exec", () => {
     });
 
     const result = spawnSync(nodeBin, [cliPath, "exec", "--", "echo", "hi"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -147,7 +169,7 @@ describe("pty exec", () => {
     await startDaemon(dir, name, "bash", [], { role: "dev", strategy: "permanent" });
 
     spawnSync(nodeBin, [cliPath, "exec", "--", "echo", "tagged"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -164,7 +186,7 @@ describe("pty exec", () => {
     await startDaemon(dir, name, "bash");
 
     const result = spawnSync(nodeBin, [cliPath, "exec", "--", "sh", "-c", "exit 42"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -190,7 +212,7 @@ describe("pty exec", () => {
 
     process.env.PTY_SESSION_DIR = dir;
     spawnSync(nodeBin, [cliPath, "exec", "--", "echo", "swapped"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -210,7 +232,7 @@ describe("pty exec", () => {
     await startDaemon(dir, name, "bash");
 
     const result = spawnSync(nodeBin, [cliPath, "exec", "--", "/nonexistent/cmd"], {
-      env: { ...process.env, PTY_SESSION_DIR: dir, PTY_SESSION: name },
+      env: execEnv(dir, name),
       encoding: "utf-8",
       timeout: 10000,
     });
@@ -218,4 +240,66 @@ describe("pty exec", () => {
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain("not found");
   }, 15000);
+
+  it("does not overwrite a concurrent metadata writer while its lock is held", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name, "bash", [], { role: "original" });
+    const previousRoot = process.env.PTY_SESSION_DIR;
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireLock(name)).toBe(true);
+    try {
+      const current = readMeta(dir, name);
+      fs.writeFileSync(path.join(dir, `${name}.json`), JSON.stringify({
+        ...current,
+        displayName: "concurrent-label",
+        tags: { ...current.tags, role: "concurrent" },
+      }));
+      const result = spawnSync(nodeBin, [cliPath, "exec", "--", "echo", "must-not-run"], {
+        env: execEnv(dir, name),
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+      expect(result.status).not.toBe(0);
+      expect(result.stderr).toContain("busy");
+      expect(readMeta(dir, name)).toMatchObject({
+        displayName: "concurrent-label",
+        tags: { role: "concurrent" },
+        displayCommand: "bash",
+      });
+    } finally {
+      releaseLock(name);
+      if (previousRoot === undefined) delete process.env.PTY_SESSION_DIR;
+      else process.env.PTY_SESSION_DIR = previousRoot;
+    }
+  }, 15000);
+
+  it("refuses to mutate or execute against a replacement generation", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    await startDaemon(dir, name, "bash", [], { role: "old" });
+    const oldGeneration = readMeta(dir, name).generation;
+    const marker = path.join(dir, "replacement-race-marker");
+    const replacement = {
+      ...readMeta(dir, name),
+      generation: "replacement-generation",
+      command: "/bin/sh",
+      args: ["-c", "sleep 30"],
+      displayCommand: "replacement command",
+      displayName: "replacement label",
+      tags: { role: "replacement" },
+    };
+    fs.writeFileSync(path.join(dir, `${name}.json`), JSON.stringify(replacement));
+
+    const result = spawnSync(
+      nodeBin,
+      [cliPath, "exec", "--", "/bin/sh", "-c", `touch ${JSON.stringify(marker)}`],
+      { env: execEnv(dir, name, oldGeneration), encoding: "utf-8", timeout: 10000 },
+    );
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("replacement generation");
+    expect(fs.existsSync(marker)).toBe(false);
+    expect(readMeta(dir, name)).toEqual(replacement);
+    expect(readEvents(dir, name).filter((event) => event.type === "session_exec")).toHaveLength(0);
+  }, 15000);
 });
diff --git a/tests/gc-abandoned.test.ts b/tests/gc-abandoned.test.ts
index 4c57390..9feafad 100644
--- a/tests/gc-abandoned.test.ts
+++ b/tests/gc-abandoned.test.ts
@@ -5,6 +5,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
+import { acquireLock, gc, isProcessAlive, releaseLock } from "../src/sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -119,6 +120,36 @@ afterEach(async () => {
 });
 
 describe("pty gc — abandoned-reap step 1.5", () => {
+  it("does not signal an abandoned session when its metadata lease is busy", async () => {
+    const dir = makeSessionDir();
+    const name = uniqueName();
+    const cwd = makeCwd();
+    const pid = await startDaemon(dir, name, cwd, "sleep", ["60"], {
+      strategy: "permanent",
+    });
+    fs.rmSync(cwd, { recursive: true, force: true });
+    const previousRoot = process.env.PTY_SESSION_DIR;
+    process.env.PTY_SESSION_DIR = dir;
+    expect(acquireLock(name)).toBe(true);
+    try {
+      const result = await gc();
+      expect(result.abandoned).toHaveLength(0);
+      expect(result.reapSkipped).toContainEqual({
+        name,
+        operation: "abandoned",
+        reason: "busy",
+        signalled: false,
+      });
+      expect(isProcessAlive(pid)).toBe(true);
+      expect(fs.existsSync(path.join(dir, `${name}.json`))).toBe(true);
+      expect(fs.existsSync(path.join(dir, `${name}.sock`))).toBe(true);
+    } finally {
+      releaseLock(name);
+      if (previousRoot === undefined) delete process.env.PTY_SESSION_DIR;
+      else process.env.PTY_SESSION_DIR = previousRoot;
+    }
+  }, 15000);
+
   it("reaps a running permanent session whose cwd has been deleted", async () => {
     const dir = makeSessionDir();
     const name = uniqueName();
diff --git a/tests/gc-generation-guard.test.ts b/tests/gc-generation-guard.test.ts
index b0a79a4..946ef40 100644
--- a/tests/gc-generation-guard.test.ts
+++ b/tests/gc-generation-guard.test.ts
@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
   cleanupObservedSession,
+  commitObservedFlapping,
   respawnPermanent,
   type SessionInfo,
   type SessionMetadata,
@@ -46,6 +47,53 @@ afterEach(async () => {
 });
 
 describe("gc generation compare-and-swap", () => {
+  it("preserves a concurrent presentation update while committing flapping", () => {
+    const root = makeRoot();
+    const name = "flap-presentation";
+    const observed = metadata(root, "same-generation", { strategy: "permanent" });
+    fs.writeFileSync(path.join(root, `${name}.json`), JSON.stringify({
+      ...observed,
+      displayName: "new presentation",
+      tags: { ...observed.tags, presentation: "current" },
+    }));
+
+    expect(commitObservedFlapping(
+      name,
+      observed,
+      { "strategy.status": "flapping" },
+      { counter: 3, limit: 3, window: 60 },
+    )).toBe(true);
+    const current = JSON.parse(fs.readFileSync(path.join(root, `${name}.json`), "utf-8"));
+    expect(current.displayName).toBe("new presentation");
+    expect(current.tags).toMatchObject({
+      presentation: "current",
+      "strategy.status": "flapping",
+    });
+    const events = fs.readFileSync(path.join(root, `${name}.events.jsonl`), "utf-8")
+      .trimEnd().split("\n").map((line) => JSON.parse(line));
+    expect(events.filter((event) => event.type === "session_flapping")).toHaveLength(1);
+  });
+
+  it("does not mark or emit against a replacement generation", () => {
+    const root = makeRoot();
+    const name = "flap-replacement";
+    const observed = metadata(root, "old", { strategy: "permanent" });
+    const replacement = metadata(root, "replacement", {
+      strategy: "permanent",
+      presentation: "replacement",
+    });
+    fs.writeFileSync(path.join(root, `${name}.json`), JSON.stringify(replacement));
+
+    expect(commitObservedFlapping(
+      name,
+      observed,
+      { "strategy.status": "flapping" },
+      { counter: 3, limit: 3, window: 60 },
+    )).toBe(false);
+    expect(JSON.parse(fs.readFileSync(path.join(root, `${name}.json`), "utf-8"))).toEqual(replacement);
+    expect(fs.existsSync(path.join(root, `${name}.events.jsonl`))).toBe(false);
+  });
+
   it("does not residual-sweep a replacement generation", async () => {
     const root = makeRoot();
     const name = "residual";
diff --git a/tests/gc-parent-child.test.ts b/tests/gc-parent-child.test.ts
index e2924d3..00836c1 100644
--- a/tests/gc-parent-child.test.ts
+++ b/tests/gc-parent-child.test.ts
@@ -5,7 +5,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
-import { acquireLock, gc, releaseLock } from "../src/sessions.ts";
+import { acquireLock, gc, isProcessAlive, releaseLock } from "../src/sessions.ts";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const nodeBin = process.execPath;
@@ -93,7 +93,7 @@ describe("pty gc — parent-child orphan-kill", () => {
     const dir = makeSessionDir();
     const blocked = uniqueName("blocked");
     const removable = uniqueName("removable");
-    await startDaemon(dir, blocked, "cat", [], { parent: "missing-parent" });
+    const blockedPid = await startDaemon(dir, blocked, "cat", [], { parent: "missing-parent" });
     await startDaemon(dir, removable, "cat", [], { parent: "missing-parent" });
     const previousRoot = process.env.PTY_SESSION_DIR;
     process.env.PTY_SESSION_DIR = dir;
@@ -102,6 +102,13 @@ describe("pty gc — parent-child orphan-kill", () => {
     try {
       const result = await gc();
       expect(result.killedOrphanChildren.map(({ name }) => name)).toEqual([removable]);
+      expect(result.reapSkipped).toContainEqual({
+        name: blocked,
+        operation: "orphan",
+        reason: "busy",
+        signalled: false,
+      });
+      expect(isProcessAlive(blockedPid)).toBe(true);
       expect(fs.existsSync(path.join(dir, `${blocked}.json`))).toBe(true);
       expect(fs.existsSync(path.join(dir, `${removable}.json`))).toBe(false);
     } finally {
diff --git a/tests/spawn-options.test.ts b/tests/spawn-options.test.ts
index fc86494..8eecde2 100644
--- a/tests/spawn-options.test.ts
+++ b/tests/spawn-options.test.ts
@@ -455,8 +455,9 @@ describe("spawnDaemon options", () => {
     expect(dumped).toContain("PTY_VERBATIM_MARKER=from-verbatim-env");
     expect(dumped).not.toContain("PTY_VERBATIM_LEAK_CANARY");
     expect(dumped).not.toContain("leaked");
-    // PTY_SESSION is always injected on top so nesting/exec keep working
+    // Stable identity and generation ownership are always injected on top.
     expect(dumped).toContain(`PTY_SESSION=${name}`);
+    expect(dumped).toMatch(/^PTY_SESSION_GENERATION=[0-9a-f]{32}$/m);
   }, 15000);
 
   it("env option combined with isolateEnv fails daemon startup", async () => {