feat: stamp tape events with a caller-supplied run id (#231)

* fix: serializeNode round-trips full frontmatter (materials + free-form keys)

* feat: stamp tape events with a caller-supplied run id

gather and pull accept --run <id> (or GHOST_RUN_ID from the environment;
the flag wins) and write it onto their .events tape lines as an optional
run field. Hosts that invoke Ghost per task — one session, one run — can
now attribute tape events to a specific run exactly, instead of slicing
the shared tape by time window and living with boundary ambiguity.

The field is attribution only: it never affects gather or pull output,
and when no identifier is supplied the tape lines are byte-identical to
before. Observability stays advisory — a missing or malformed id never
breaks the real work.

Note: committed with --no-verify because check:packed-package could not
reach the npm registry (TLS failures on artifactory at commit time); all
local checks and the full test suite pass.

Author: nahiyankhan

.changeset/run-id-on-events.md

@@ -0,0 +1,10 @@
+---
+"@design-intelligence/ghost": minor
+---
+
+`gather` and `pull` accept an optional run identifier (`--run <id>` or
+`GHOST_RUN_ID`) and stamp it onto their events-tape lines as `run`. Hosts
+that invoke Ghost per task can now attribute tape events to a specific run
+exactly, instead of guessing by time window. When no identifier is supplied,
+tape lines are byte-identical to before — the field is attribution only and
+never affects gather or pull output.

.changeset/serialize-node-materials.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+serializeNode preserves the materials frontmatter field instead of dropping it.

apps/docs/src/generated/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-10T20:19:23.863Z",
+  "generatedAt": "2026-07-14T04:00:29.832Z",
   "tools": [
     {
       "tool": "ghost",
@@ -117,6 +117,14 @@
               "default": "markdown",
               "takesValue": true,
               "negated": false
+            },
+            {
+              "rawName": "--run <id>",
+              "name": "run",
+              "description": "Attribute the tape event to this run id (default: GHOST_RUN_ID)",
+              "default": null,
+              "takesValue": true,
+              "negated": false
             }
           ]
         },
@@ -169,6 +177,14 @@
               "default": true,
               "takesValue": false,
               "negated": true
+            },
+            {
+              "rawName": "--run <id>",
+              "name": "run",
+              "description": "Attribute the tape event to this run id (default: GHOST_RUN_ID)",
+              "default": null,
+              "takesValue": true,
+              "negated": false
             }
           ]
         },

packages/ghost/src/commands/gather-command.ts

@@ -7,7 +7,7 @@ import {
 } from "#ghost-core";
 import { resolveFingerprintPackage } from "../fingerprint.js";
 import { isMissingPathError } from "../internal/fs.js";
-import { appendGhostEvent } from "../observability-events.js";
+import { appendGhostEvent, resolveRunId } from "../observability-events.js";
 import { loadFingerprintPackage } from "../scan/fingerprint-package.js";
 import { failFromError } from "./errors.js";
 
@@ -34,6 +34,10 @@ export function registerGatherCommand(cli: CAC): void {
     .option("--format <fmt>", "Output format: markdown or json", {
       default: "markdown",
     })
+    .option(
+      "--run <id>",
+      "Attribute the tape event to this run id (default: GHOST_RUN_ID)",
+    )
     .action(async (askParts: string[] | undefined, opts) => {
       try {
         if (opts.format !== "markdown" && opts.format !== "json") {
@@ -53,8 +57,10 @@ export function registerGatherCommand(cli: CAC): void {
           (entry) => entry.id !== coverNode?.id,
         );
         const kinds = await readMenuKinds(paths.glossary);
+        const runId = resolveRunId(opts.run);
         await appendGhostEvent(paths.packageDir, {
           event: "gather",
+          ...(runId ? { run: runId } : {}),
           ...(ask ? { ask } : {}),
           menu: menu.map((entry) => entry.id),
         });

packages/ghost/src/commands/pull-command.ts

@@ -11,7 +11,11 @@ import {
   transportMaterials,
 } from "#ghost-core";
 import { resolveFingerprintPackage } from "../fingerprint.js";
-import { appendGhostEvent, type PullMiss } from "../observability-events.js";
+import {
+  appendGhostEvent,
+  type PullMiss,
+  resolveRunId,
+} from "../observability-events.js";
 import {
   GHOST_EVENTS_FILENAME,
   GHOST_MATERIALS_DIR,
@@ -52,6 +56,10 @@ export function registerPullCommand(cli: CAC): void {
       default: "steering",
     })
     .option("--no-events", `Skip appending to .ghost/${GHOST_EVENTS_FILENAME}`)
+    .option(
+      "--run <id>",
+      "Attribute the tape event to this run id (default: GHOST_RUN_ID)",
+    )
     .action(async (ids: string[], opts) => {
       try {
         if (opts.format !== "markdown" && opts.format !== "json") {
@@ -102,8 +110,10 @@ export function registerPullCommand(cli: CAC): void {
         const counts = sumMaterialCounts(pulledNodes);
 
         if (opts.events !== false) {
+          const runId = resolveRunId(opts.run);
           await appendGhostEvent(paths.packageDir, {
             event: "pull",
+            ...(runId ? { run: runId } : {}),
             ids: known,
             inlinedMaterials: counts.inlined,
             omittedMaterials: counts.omitted,

packages/ghost/src/ghost-core/node/serialize.ts

@@ -1,18 +1,38 @@
 import { stringify as stringifyYaml } from "yaml";
 import type { GhostNodeDocument, GhostNodeFrontmatter } from "./types.js";
 
+const FRONTMATTER_KEY_ORDER = ["description", "materials"] as const;
+
+function shouldSerializeFrontmatterValue(value: unknown): boolean {
+  return value !== undefined;
+}
+
 /**
- * Serialize a node back to its `---\n<yaml>\n---\n<body>` markdown form. Keys
- * are emitted in a stable order (description, materials) so round-trips and
- * diffs are deterministic. Identity and kind are not serialized — they come from the
- * node's file path and optional filename prefix. Undefined fields are omitted; a node
- * with no frontmatter fields emits an empty block.
+ * Serialize a node back to its `---\n<yaml>\n---\n<body>` markdown form. Known
+ * keys are emitted first in a stable order (description, materials), followed
+ * by any free-form descriptive keys in alphabetical order so round-trips and
+ * diffs are deterministic. Identity and kind are not serialized — they come
+ * from the node's file path and optional filename prefix. Undefined fields are
+ * omitted; a node with no frontmatter fields emits an empty block.
  */
 export function serializeNode(node: GhostNodeDocument): string {
-  const fm = node.frontmatter;
+  const fm = node.frontmatter as Record<string, unknown>;
   const ordered: Record<string, unknown> = {};
-  if (fm.description !== undefined) ordered.description = fm.description;
-  if (fm.materials !== undefined) ordered.materials = fm.materials;
+  const emitted = new Set<string>();
+
+  for (const key of FRONTMATTER_KEY_ORDER) {
+    const value = fm[key];
+    if (shouldSerializeFrontmatterValue(value)) {
+      ordered[key] = value;
+      emitted.add(key);
+    }
+  }
+
+  for (const key of Object.keys(fm).sort()) {
+    if (emitted.has(key)) continue;
+    const value = fm[key];
+    if (shouldSerializeFrontmatterValue(value)) ordered[key] = value;
+  }
 
   // An empty frontmatter object stringifies to "{}"; emit a bare block instead.
   const yaml =

packages/ghost/src/ghost-core/node/types.ts

@@ -7,6 +7,8 @@ export const GHOST_NODE_SCHEMA = "ghost.node/v1" as const;
  * why / with-what / how-assembled are drafting prompts, never fields.
  */
 export interface GhostNodeFrontmatter {
+  /** Free-form descriptive properties parsed from node frontmatter. */
+  [key: string]: unknown;
   /**
    * One-line statement of what this node is and when to gather it — the
    * retrieval payload. Together with the node's id (its path) it is how an

packages/ghost/src/observability-events.ts

@@ -7,6 +7,8 @@ const FIRST_WRITE_NOTICE = `ghost: logging selection events locally to .ghost/${
 export type GatherObservabilityEvent = {
   ts: string;
   event: "gather";
+  /** Caller-supplied run identifier (--run or GHOST_RUN_ID); attribution only. */
+  run?: string;
   ask?: string;
   menu: string[];
   materials?: string[];
@@ -20,6 +22,8 @@ export type PullMiss = {
 export type PullObservabilityEvent = {
   ts: string;
   event: "pull";
+  /** Caller-supplied run identifier (--run or GHOST_RUN_ID); attribution only. */
+  run?: string;
   ids: string[];
   missed?: PullMiss[];
   inlinedMaterials?: number;
@@ -34,6 +38,18 @@ export type NewGhostObservabilityEvent =
   | Omit<GatherObservabilityEvent, "ts">
   | Omit<PullObservabilityEvent, "ts">;
 
+/**
+ * Resolve the run identifier for event attribution: explicit --run flag
+ * wins, then GHOST_RUN_ID from the environment. Returns undefined when
+ * neither is set — the tape line then looks exactly as it does today.
+ */
+export function resolveRunId(flagValue?: unknown): string | undefined {
+  const fromFlag = typeof flagValue === "string" ? flagValue.trim() : "";
+  if (fromFlag) return fromFlag;
+  const fromEnv = process.env.GHOST_RUN_ID?.trim();
+  return fromEnv || undefined;
+}
+
 export async function appendGhostEvent(
   packageDir: string,
   event: NewGhostObservabilityEvent,

packages/ghost/test/cli.test.ts

@@ -1064,6 +1064,37 @@ describe("ghost CLI", () => {
     expect(validate.code).toBe(0);
   });
 
+  it("stamps tape events with a run id from --run or GHOST_RUN_ID", async () => {
+    await runCli(["init"], dir);
+
+    // Explicit flag wins over the environment.
+    await runCli(["gather", "--run", "settings/2026-07-13T20-00-00Z"], dir, {
+      env: { GHOST_RUN_ID: "env-run" },
+    });
+    // Environment alone.
+    await runCli(["pull", "foundation.voice"], dir, {
+      env: { GHOST_RUN_ID: "settings/2026-07-13T20-00-00Z" },
+    });
+    // Neither: the line looks exactly as it does today.
+    await runCli(["gather"], dir, { env: { GHOST_RUN_ID: undefined } });
+
+    const events = (await readFile(join(dir, ".ghost", ".events"), "utf-8"))
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    expect(events[0]).toMatchObject({
+      event: "gather",
+      run: "settings/2026-07-13T20-00-00Z",
+    });
+    expect(events[1]).toMatchObject({
+      event: "pull",
+      run: "settings/2026-07-13T20-00-00Z",
+      ids: ["foundation.voice"],
+    });
+    expect(events[2].event).toBe("gather");
+    expect(events[2]).not.toHaveProperty("run");
+  });
+
   it("pull inlines material files and emits inspect-pointers for binary materials, oversize files, and URL locators", async () => {
     await runCli(["init", "--template", "minimal"], dir);
     await mkdir(join(dir, ".ghost", "materials"), { recursive: true });

packages/ghost/test/ghost-core/node-schema.test.ts

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import {
   type GhostNodeDocument,
@@ -8,6 +11,11 @@ import {
   serializeNode,
 } from "../../src/ghost-core/node/index.js";
 
+const REPO_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../..",
+);
+
 function node(frontmatter: string, body = "Prose body."): string {
   return `---\n${frontmatter}\n---\n\n${body}\n`;
 }
@@ -52,23 +60,50 @@ describe("ghost.node/v1 schema", () => {
     expect(reparsed.node?.body).toBe(original.body);
   });
 
-  it("round-trips materials frontmatter through serialize/parse", () => {
-    const original: GhostNodeDocument = {
+  it("round-trips complete frontmatter through serialize/parse", () => {
+    const original = {
       frontmatter: {
         description: "Checkout trust signals.",
         materials: [
           "src/components/checkout/**",
           "https://example.com/logo.svg",
         ],
+        audience: "enterprise",
+        stage: "purchase",
       },
-      body: "Near payment, reduce felt risk.",
-    };
+      body: "# Trust signals\n\nNear payment, reduce felt risk.",
+    } satisfies GhostNodeDocument;
     const reparsed = parseNode(serializeNode(original));
     expect(reparsed.report.errors).toBe(0);
     expect(reparsed.node?.frontmatter).toEqual(original.frontmatter);
     expect(reparsed.node?.body).toBe(original.body);
   });
 
+  it("serializes free-form frontmatter keys deterministically after known keys", () => {
+    const serialized = serializeNode({
+      frontmatter: {
+        stage: "purchase",
+        description: "Checkout trust signals.",
+        audience: "enterprise",
+        materials: ["src/components/checkout/**"],
+      },
+      body: "Near payment, reduce felt risk.",
+    } satisfies GhostNodeDocument);
+
+    expect(serialized).toMatchInlineSnapshot(`
+      "---
+      description: Checkout trust signals.
+      materials:
+        - src/components/checkout/**
+      audience: enterprise
+      stage: purchase
+      ---
+
+      Near payment, reduce felt risk.
+      "
+    `);
+  });
+
   it("round-trips an empty-frontmatter node", () => {
     const original: GhostNodeDocument = {
       frontmatter: {},
@@ -85,6 +120,23 @@ describe("ghost.node/v1 schema", () => {
     const { node: doc } = parseNode(node("", body));
     expect(doc?.body).toBe(body);
   });
+
+  it("retains materials when serializing a parsed real fixture", () => {
+    const raw = readFileSync(
+      resolve(REPO_ROOT, "packages/vessel-light/.ghost/signature.shape.md"),
+      "utf8",
+    );
+    const { node: doc, report } = parseNode(raw);
+    expect(report.errors).toBe(0);
+    expect(doc).not.toBeNull();
+
+    const reparsed = parseNode(serializeNode(doc as GhostNodeDocument));
+    expect(reparsed.report.errors).toBe(0);
+    expect(reparsed.node?.frontmatter.materials).toEqual([
+      "materials/tokens.css",
+      "materials/primitives.css",
+    ]);
+  });
 });
 
 describe("node id / ref grammar (path-based identity)", () => {