fix(server): stamp built commit into service.version (#11748)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server emits OpenTelemetry spans so operators can trace agent
work
> - Each span needs a service version that identifies the code that
produced it
> - The current service version comes from a static environment value
and can become stale after a rebuild
> - This pull request records the built commit and resolves the service
version from the build stamp, runtime Git, the environment, or an
unknown fallback
> - The benefit is trace data that identifies the correct built commit
during development and deployment

## Linked Issues or Issue Description

**What happened?**

The server used a static `OTEL_SERVICE_VERSION` value for every
OpenTelemetry span. Rebuilds could produce traces with an old commit
value.

**Expected behavior**

The server should report the built commit when a build stamp exists. It
should use runtime Git, the environment value, or `unknown` as fallback.

**Steps to reproduce**

1. Set `OTEL_SERVICE_VERSION` to an old commit value.
2. Build the server at a different commit.
3. Start the server and inspect the OpenTelemetry service version.
4. Confirm that the built commit takes precedence over the old
environment value.

## What Changed

- Add a build script that writes the short Git commit to
`dist/build-info.json`.
- Resolve `service.version` from the build stamp, runtime Git, the
environment, or `unknown`.
- Log the resolved service version once during server startup.
- Add tests for the resolution order and safe behavior without Git.
- Document the resolution order in `doc/observability.md`.

## Verification

- `pnpm --filter @paperclipai/server build`
- `npx vitest run server/src/__tests__/service-version.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- Confirm that the build stamp contains the short commit.
- Confirm that the stamp wins over the environment value.
- Confirm that a build without Git exits successfully without a stamp.

## Risks

The server now prefers the built commit over `OTEL_SERVICE_VERSION`. A
build without Git uses the existing environment value or `unknown`. The
change needs no schema migration and has a single-commit rollback path.

## Model Used

OpenAI Codex, GPT-5, tool use and code execution. The runtime does not
expose the context window size or reasoning mode.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

server/scripts/write-build-stamp.mjs

@@ -0,0 +1,87 @@
+// Write the build stamp for the server.
+//
+// The server `build` script runs this after `tsc`. It writes the commit SHA
+// into `dist/build-info.json`. The instrumentation module reads that stamp to
+// report `service.version`, so the value tracks the true built commit.
+//
+// The build resolves the commit in two steps:
+//   1. `git rev-parse --short HEAD` in the server directory.
+//   2. The `PAPERCLIP_BUILD_COMMIT` environment variable.
+// A Docker image build excludes `.git`, so the git lookup fails there. The
+// image build passes the commit in `PAPERCLIP_BUILD_COMMIT` instead, so the
+// stamp still records the true built commit.
+//
+// The build must not fail when no commit is available. A missing `git`, a
+// checkout with no `.git`, and an unset `PAPERCLIP_BUILD_COMMIT` together write
+// no stamp and exit 0.
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const serverDir = join(scriptDir, "..");
+const distDir = join(serverDir, "dist");
+const outFile = join(distDir, "build-info.json");
+
+/**
+ * Resolve the commit for the build stamp. Prefer the git commit. Fall back to
+ * the supplied commit — the value a Docker image build passes in
+ * `PAPERCLIP_BUILD_COMMIT` when `.git` is absent. Return null when neither
+ * source gives a non-empty value.
+ *
+ * @param {unknown} gitCommit The `git rev-parse` result, or null on failure.
+ * @param {unknown} suppliedCommit The `PAPERCLIP_BUILD_COMMIT` value.
+ * @returns {string | null}
+ */
+export function resolveBuildCommit(gitCommit, suppliedCommit) {
+  const git = typeof gitCommit === "string" ? gitCommit.trim() : "";
+  if (git) return git;
+  const supplied = typeof suppliedCommit === "string" ? suppliedCommit.trim() : "";
+  if (supplied) return supplied;
+  return null;
+}
+
+/**
+ * Read the short commit SHA with `git rev-parse --short HEAD` in the server
+ * directory. Return the SHA, or null on any failure.
+ *
+ * @returns {string | null}
+ */
+function readGitCommit() {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: serverDir,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the commit and write the build stamp. Write no stamp and return when
+ * no commit is available, so the build continues.
+ */
+function main() {
+  const commit = resolveBuildCommit(readGitCommit(), process.env.PAPERCLIP_BUILD_COMMIT);
+
+  if (!commit) {
+    console.log("[build-stamp] no commit available; wrote no build stamp");
+    return;
+  }
+
+  mkdirSync(distDir, { recursive: true });
+  writeFileSync(outFile, `${JSON.stringify({ commit }, null, 2)}\n`);
+  console.log(`[build-stamp] wrote ${outFile} commit=${commit}`);
+}
+
+// Run only when node invokes this file directly (the `build` script). A test
+// that imports `resolveBuildCommit` does not run `main`.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}