fix(server): preserve source SHA without Git metadata (#9638)

## Thinking Path

> - Paperclip is the open source control plane people use to manage
AI-agent companies
> - Operators need to identify the exact source build running from the
persistent account menu
> - PR #9508 added linked source SHA metadata when the server can
inspect its Git checkout
> - Production images and packaged deployments may not include a `.git`
directory even though their build commit is known
> - Falling back to the package version in those environments makes the
UI look like a formal release and hides the source SHA
> - This pull request reads a validated deployment commit marker when
Git metadata is unavailable and uses it consistently for server version
and server-info responses
> - The benefit is that unreleased deployments keep showing an
inspectable SHA without changing exact-tag release versions

## Linked Issues or Issue Description

Follow-up to #9508.

### Pre-submission checklist

- [x] I searched existing open and closed issues and found no duplicate
for the no-`.git` deployment fallback.
- [x] The behavior reproduces when the server runs without Git metadata
but has a known build commit.
- [x] The behavior originates in Paperclip's core server build metadata
handling, not an adapter, provider, or local configuration.

### What happened?

PR #9508 displays source branch and SHA metadata for unreleased builds,
but server version and server-info resolution still fall back to the
package version when the runtime has no `.git` directory. This is common
in production images and packaged deployments.

### Expected behavior

When a validated deployment commit is available through
`PAPERCLIP_BUILD_COMMIT` or `/app/.paperclip-build-commit`, the server
should retain a derived source version and expose SHA metadata even if
Git commands are unavailable. Exact release tags should continue using
the formal package version.

### Steps to reproduce

1. Build or run Paperclip without a `.git` directory.
2. Provide a full commit SHA through `PAPERCLIP_BUILD_COMMIT` or
`/app/.paperclip-build-commit`.
3. Start the server and inspect the version and server-info output.
4. Observe that current `master` returns only the package version and
reports Git metadata unavailable.

### Paperclip version or commit

Current `master` after #9508.

### Deployment mode

Packaged or containerized deployments without runtime Git metadata.

### Installation method

Built from source or deployment image.

## What Changed

- Add validated build-commit parsing from `PAPERCLIP_BUILD_COMMIT` and
`/app/.paperclip-build-commit`.
- Preserve source-derived server versions when Git commands are
unavailable.
- Expose fallback SHA metadata through server-info with an explicit
unavailable local-status state.
- Keep exact release-tag builds on the formal package version.
- Add focused regression tests for parsing, version resolution, and
server-info fallback behavior.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/build-commit.test.ts src/__tests__/server-info.test.ts
src/__tests__/version.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- `git diff --check public/master...HEAD`

## Risks

- Low risk: only full 40-character hexadecimal commit values are
accepted; malformed or truncated markers preserve the existing fallback
behavior.
- Deployment tooling must set `PAPERCLIP_BUILD_COMMIT` or write
`/app/.paperclip-build-commit` for the fallback to activate.
- Fallback server-info cannot provide branch, subject, commit time, or
working-tree status without Git metadata, so those fields remain
explicitly unavailable.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex using GPT-5.4 with medium reasoning, repository/tool
access, shell execution, and code editing; context-window size was not
exposed by the runtime.

## 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 pass
- [x] Greptile review is 5/5 with no open P2-or-higher comments,
recommendations, or follow-ups

---------

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

server/src/__tests__/build-commit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseBuildCommit, readBuildCommit } from "../build-commit.js";
+
+describe("parseBuildCommit", () => {
+  it("normalizes a full deployment commit", () => {
+    expect(parseBuildCommit("  ABCDEF0123456789ABCDEF0123456789ABCDEF01\n")).toBe(
+      "abcdef0123456789abcdef0123456789abcdef01",
+    );
+  });
+
+  it("rejects truncated and malformed commits", () => {
+    expect(parseBuildCommit("abcdef0")).toBeNull();
+    expect(parseBuildCommit("not-a-commit")).toBeNull();
+  });
+});
+
+describe("readBuildCommit", () => {
+  it("prefers an explicit environment commit", () => {
+    const readTextFile = vi.fn(() => "ffffffffffffffffffffffffffffffffffffffff");
+
+    expect(
+      readBuildCommit({
+        environmentCommit: "0123456789abcdef0123456789abcdef01234567",
+        readTextFile,
+      }),
+    ).toBe("0123456789abcdef0123456789abcdef01234567");
+    expect(readTextFile).not.toHaveBeenCalled();
+  });
+
+  it("reads the deployment marker when no environment commit is set", () => {
+    expect(
+      readBuildCommit({
+        environmentCommit: null,
+        buildCommitPath: "/app/.paperclip-build-commit",
+        readTextFile: (path) => {
+          expect(path).toBe("/app/.paperclip-build-commit");
+          return "0123456789abcdef0123456789abcdef01234567\n";
+        },
+      }),
+    ).toBe("0123456789abcdef0123456789abcdef01234567");
+  });
+});

server/src/__tests__/server-info.test.ts

@@ -129,6 +129,7 @@ describe("server info snapshot", () => {
       gitCommand: () => {
         throw new Error("fatal: not a git repository");
       },
+      buildCommitCommand: () => null,
     });
 
     expect(snapshot).toEqual({
@@ -139,6 +140,32 @@ describe("server info snapshot", () => {
       },
     });
   });
+
+  it("uses deployment commit metadata when the runtime has no git directory", () => {
+    const snapshot = createServerInfoSnapshot({
+      now: new Date("2026-06-26T00:00:00.000Z"),
+      gitCommand: () => {
+        throw new Error("fatal: not a git repository");
+      },
+      buildCommitCommand: () => "0123456789abcdef0123456789abcdef01234567",
+    });
+
+    expect(snapshot).toEqual({
+      processStartedAt: "2026-06-26T00:00:00.000Z",
+      git: {
+        available: true,
+        fullSha: "0123456789abcdef0123456789abcdef01234567",
+        shortSha: "0123456",
+        branchName: null,
+        subject: "Source build",
+        committedAt: null,
+        localChanges: {
+          available: false,
+          unavailableReason: "git_status_unavailable",
+        },
+      },
+    });
+  });
 });
 
 describe("getServerInfoSnapshot", () => {

server/src/__tests__/version.test.ts

@@ -40,6 +40,28 @@ describe("resolveServerVersion", () => {
     ).toBe("2026.626.0+58.git.518fc71ce");
   });
 
+  it("keeps the package version when git describe output is unparseable", () => {
+    expect(
+      resolveServerVersion({
+        buildCommit: "0123456789abcdef0123456789abcdef01234567",
+        packageVersion: "2026.706.0",
+        gitDescribeCommand: () => "canary/v2026.706.0-canary.1",
+        debugLog: vi.fn(),
+      }),
+    ).toBe("2026.706.0");
+  });
+
+  it("keeps the formal version for an exact release tag even when build metadata exists", () => {
+    expect(
+      resolveServerVersion({
+        buildCommit: "0123456789abcdef0123456789abcdef01234567",
+        packageVersion: "2026.706.0",
+        gitDescribeCommand: () => "v2026.706.0-0-g012345678\n",
+        debugLog: vi.fn(),
+      }),
+    ).toBe("2026.706.0");
+  });
+
   it("falls back to package version without throwing when git is unavailable", () => {
     const debugLog = vi.fn();
     const cause = new Error("spawn git ENOENT");
@@ -52,6 +74,7 @@ describe("resolveServerVersion", () => {
 
     expect(
       resolveServerVersion({
+        buildCommit: null,
         packageVersion: "2026.706.0",
         gitDescribeCommand: () => {
           throw err;
@@ -75,11 +98,25 @@ describe("resolveServerVersion", () => {
     );
   });
 
+  it("uses deployment commit metadata when a source build has no git directory", () => {
+    expect(
+      resolveServerVersion({
+        buildCommit: "0123456789abcdef0123456789abcdef01234567",
+        packageVersion: "2026.706.0",
+        gitDescribeCommand: () => {
+          throw new Error("fatal: not a git repository");
+        },
+        debugLog: vi.fn(),
+      }),
+    ).toBe("2026.706.0+0.git.0123456");
+  });
+
   it("skips git metadata probing for packaged installs under node_modules", () => {
     const debugLog = vi.fn();
 
     expect(
       resolveServerVersion({
+        buildCommit: "0123456789abcdef0123456789abcdef01234567",
         packageVersion: "2026.707.0-canary.12",
         debugLog,
         packageRoot: "/tmp/npm/_npx/example/node_modules/@paperclipai/server",
@@ -98,6 +135,7 @@ describe("resolveServerVersion", () => {
 
     expect(
       resolveServerVersion({
+        buildCommit: null,
         packageVersion: "2026.707.0-canary.12",
         debugLog,
         gitDescribeCommand,
@@ -119,6 +157,7 @@ describe("resolveServerVersion", () => {
     try {
       expect(
         resolveServerVersion({
+          buildCommit: null,
           packageVersion: "2026.706.0",
           gitDescribeCommand: () => {
             throw new Error("fatal: not a git repository");