Surface environment and repository identity metadata

- Persist a stable server environment ID and descriptor
- Resolve repository identity from git remotes and enrich orchestration events
- Thread environment metadata through desktop and web startup flows

Author: juliusmarminge

apps/desktop/src/main.ts

@@ -60,6 +60,7 @@ const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
 const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
 const UPDATE_CHECK_CHANNEL = "desktop:update-check";
 const GET_WS_URL_CHANNEL = "desktop:get-ws-url";
+const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
 const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
 const STATE_DIR = Path.join(BASE_DIR, "userdata");
 const DESKTOP_SCHEME = "t3";
@@ -1172,6 +1173,14 @@ function registerIpcHandlers(): void {
     event.returnValue = backendWsUrl;
   });
 
+  ipcMain.removeAllListeners(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL);
+  ipcMain.on(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL, (event) => {
+    event.returnValue = {
+      label: "Local environment",
+      wsUrl: backendWsUrl || null,
+    } as const;
+  });
+
   ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
   ipcMain.handle(PICK_FOLDER_CHANNEL, async () => {
     const owner = BrowserWindow.getFocusedWindow() ?? mainWindow;

apps/desktop/src/preload.ts

@@ -13,12 +13,20 @@ const UPDATE_CHECK_CHANNEL = "desktop:update-check";
 const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
 const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
 const GET_WS_URL_CHANNEL = "desktop:get-ws-url";
+const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
 
 contextBridge.exposeInMainWorld("desktopBridge", {
   getWsUrl: () => {
     const result = ipcRenderer.sendSync(GET_WS_URL_CHANNEL);
     return typeof result === "string" ? result : null;
   },
+  getLocalEnvironmentBootstrap: () => {
+    const result = ipcRenderer.sendSync(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL);
+    if (typeof result !== "object" || result === null) {
+      return null;
+    }
+    return result as ReturnType<DesktopBridge["getLocalEnvironmentBootstrap"]>;
+  },
   pickFolder: () => ipcRenderer.invoke(PICK_FOLDER_CHANNEL),
   confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
   setTheme: (theme) => ipcRenderer.invoke(SET_THEME_CHANNEL, theme),

apps/server/src/environment/Layers/ServerEnvironment.test.ts

@@ -0,0 +1,33 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { expect, it } from "@effect/vitest";
+import { Effect, FileSystem, Layer } from "effect";
+
+import { ServerConfig } from "../../config.ts";
+import { ServerEnvironment } from "../Services/ServerEnvironment.ts";
+import { ServerEnvironmentLive } from "./ServerEnvironment.ts";
+
+const makeServerEnvironmentLayer = (baseDir: string) =>
+  ServerEnvironmentLive.pipe(Layer.provide(ServerConfig.layerTest(process.cwd(), baseDir)));
+
+it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
+  it.effect("persists the environment id across service restarts", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-server-environment-test-",
+      });
+
+      const first = yield* Effect.gen(function* () {
+        const serverEnvironment = yield* ServerEnvironment;
+        return yield* serverEnvironment.getDescriptor;
+      }).pipe(Effect.provide(makeServerEnvironmentLayer(baseDir)));
+      const second = yield* Effect.gen(function* () {
+        const serverEnvironment = yield* ServerEnvironment;
+        return yield* serverEnvironment.getDescriptor;
+      }).pipe(Effect.provide(makeServerEnvironmentLayer(baseDir)));
+
+      expect(first.environmentId).toBe(second.environmentId);
+      expect(second.capabilities.repositoryIdentity).toBe(true);
+    }),
+  );
+});

apps/server/src/environment/Layers/ServerEnvironment.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { EnvironmentId, type ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
+import { Effect, FileSystem, Layer, Path } from "effect";
+
+import { ServerConfig } from "../../config.ts";
+import { ServerEnvironment, type ServerEnvironmentShape } from "../Services/ServerEnvironment.ts";
+import { version } from "../../../package.json" with { type: "json" };
+
+const ENVIRONMENT_ID_FILENAME = "environment-id";
+
+function platformOs(): ExecutionEnvironmentDescriptor["platform"]["os"] {
+  switch (process.platform) {
+    case "darwin":
+      return "darwin";
+    case "linux":
+      return "linux";
+    case "win32":
+      return "windows";
+    default:
+      return "unknown";
+  }
+}
+
+function platformArch(): ExecutionEnvironmentDescriptor["platform"]["arch"] {
+  switch (process.arch) {
+    case "arm64":
+      return "arm64";
+    case "x64":
+      return "x64";
+    default:
+      return "other";
+  }
+}
+
+export const makeServerEnvironment = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const serverConfig = yield* ServerConfig;
+  const environmentIdPath = path.join(serverConfig.stateDir, ENVIRONMENT_ID_FILENAME);
+
+  const readPersistedEnvironmentId = Effect.gen(function* () {
+    const exists = yield* fileSystem
+      .exists(environmentIdPath)
+      .pipe(Effect.orElseSucceed(() => false));
+    if (!exists) {
+      return null;
+    }
+
+    const raw = yield* fileSystem.readFileString(environmentIdPath).pipe(
+      Effect.orElseSucceed(() => ""),
+      Effect.map((value) => value.trim()),
+    );
+
+    return raw.length > 0 ? raw : null;
+  });
+
+  const persistEnvironmentId = (value: string) =>
+    fileSystem.writeFileString(environmentIdPath, `${value}\n`);
+
+  const environmentIdRaw = yield* readPersistedEnvironmentId.pipe(
+    Effect.flatMap((persisted) => {
+      if (persisted) {
+        return Effect.succeed(persisted);
+      }
+
+      const generated = randomUUID();
+      return persistEnvironmentId(generated).pipe(Effect.as(generated));
+    }),
+  );
+
+  const environmentId = EnvironmentId.makeUnsafe(environmentIdRaw);
+  const cwdBaseName = path.basename(serverConfig.cwd).trim();
+  const label =
+    serverConfig.mode === "desktop"
+      ? "Local environment"
+      : cwdBaseName.length > 0
+        ? cwdBaseName
+        : "T3 environment";
+
+  const descriptor: ExecutionEnvironmentDescriptor = {
+    environmentId,
+    label,
+    platform: {
+      os: platformOs(),
+      arch: platformArch(),
+    },
+    serverVersion: version,
+    capabilities: {
+      repositoryIdentity: true,
+    },
+  };
+
+  return {
+    getEnvironmentId: Effect.succeed(environmentId),
+    getDescriptor: Effect.succeed(descriptor),
+  } satisfies ServerEnvironmentShape;
+});
+
+export const ServerEnvironmentLive = Layer.effect(ServerEnvironment, makeServerEnvironment);

apps/server/src/environment/Services/ServerEnvironment.ts

@@ -0,0 +1,13 @@
+import type { EnvironmentId, ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
+import { ServiceMap } from "effect";
+import type { Effect } from "effect";
+
+export interface ServerEnvironmentShape {
+  readonly getEnvironmentId: Effect.Effect<EnvironmentId>;
+  readonly getDescriptor: Effect.Effect<ExecutionEnvironmentDescriptor>;
+}
+
+export class ServerEnvironment extends ServiceMap.Service<
+  ServerEnvironment,
+  ServerEnvironmentShape
+>()("t3/environment/Services/ServerEnvironment") {}

apps/server/src/git/Layers/GitManager.test.ts

@@ -854,7 +854,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
           "pr list --head jasonLaster:statemachine --state all --limit 20 --json number,title,url,baseRefName,headRefName,state,mergedAt,updatedAt,isCrossRepository,headRepository,headRepositoryOwner",
         );
       }),
-    12_000,
+    20_000,
   );
 
   it.effect(
@@ -962,7 +962,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
           ),
         ).toBe(false);
       }),
-    12_000,
+    20_000,
   );
 
   it.effect("status returns merged PR state when latest PR was merged", () =>
@@ -1685,7 +1685,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
           false,
         );
       }),
-    12_000,
+    20_000,
   );
 
   it.effect(

apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts

@@ -234,6 +234,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           id: asProjectId("project-1"),
           title: "Project 1",
           workspaceRoot: "/tmp/project-1",
+          repositoryIdentity: null,
           defaultModelSelection: {
             provider: "codex",
             model: "gpt-5-codex",

apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts

@@ -38,6 +38,8 @@ import { ProjectionThreadMessage } from "../../persistence/Services/ProjectionTh
 import { ProjectionThreadProposedPlan } from "../../persistence/Services/ProjectionThreadProposedPlans.ts";
 import { ProjectionThreadSession } from "../../persistence/Services/ProjectionThreadSessions.ts";
 import { ProjectionThread } from "../../persistence/Services/ProjectionThreads.ts";
+import { RepositoryIdentityResolverLive } from "../../project/Layers/RepositoryIdentityResolver.ts";
+import { RepositoryIdentityResolver } from "../../project/Services/RepositoryIdentityResolver.ts";
 import { ORCHESTRATION_PROJECTOR_NAMES } from "./ProjectionPipeline.ts";
 import {
   ProjectionSnapshotQuery,
@@ -163,6 +165,8 @@ function toPersistenceSqlOrDecodeError(sqlOperation: string, decodeOperation: st
 
 const makeProjectionSnapshotQuery = Effect.gen(function* () {
   const sql = yield* SqlClient.SqlClient;
+  const repositoryIdentityResolver = yield* RepositoryIdentityResolver;
+  const repositoryIdentityResolutionConcurrency = 4;
 
   const listProjectRows = SqlSchema.findAll({
     Request: Schema.Void,
@@ -652,10 +656,22 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
             });
           }
 
+          const repositoryIdentities = new Map(
+            yield* Effect.forEach(
+              projectRows,
+              (row) =>
+                repositoryIdentityResolver
+                  .resolve(row.workspaceRoot)
+                  .pipe(Effect.map((identity) => [row.projectId, identity] as const)),
+              { concurrency: repositoryIdentityResolutionConcurrency },
+            ),
+          );
+
           const projects: ReadonlyArray<OrchestrationProject> = projectRows.map((row) => ({
             id: row.projectId,
             title: row.title,
             workspaceRoot: row.workspaceRoot,
+            repositoryIdentity: repositoryIdentities.get(row.projectId) ?? null,
             defaultModelSelection: row.defaultModelSelection,
             scripts: row.scripts,
             createdAt: row.createdAt,
@@ -732,19 +748,25 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
             "ProjectionSnapshotQuery.getActiveProjectByWorkspaceRoot:decodeRow",
           ),
         ),
-        Effect.map(
-          Option.map(
-            (row): OrchestrationProject => ({
-              id: row.projectId,
-              title: row.title,
-              workspaceRoot: row.workspaceRoot,
-              defaultModelSelection: row.defaultModelSelection,
-              scripts: row.scripts,
-              createdAt: row.createdAt,
-              updatedAt: row.updatedAt,
-              deletedAt: row.deletedAt,
-            }),
-          ),
+        Effect.map((option) => option),
+        Effect.flatMap((option) =>
+          Option.isNone(option)
+            ? Effect.succeed(Option.none<OrchestrationProject>())
+            : repositoryIdentityResolver.resolve(option.value.workspaceRoot).pipe(
+                Effect.map((repositoryIdentity) =>
+                  Option.some({
+                    id: option.value.projectId,
+                    title: option.value.title,
+                    workspaceRoot: option.value.workspaceRoot,
+                    repositoryIdentity,
+                    defaultModelSelection: option.value.defaultModelSelection,
+                    scripts: option.value.scripts,
+                    createdAt: option.value.createdAt,
+                    updatedAt: option.value.updatedAt,
+                    deletedAt: option.value.deletedAt,
+                  } satisfies OrchestrationProject),
+                ),
+              ),
         ),
       );
 
@@ -816,4 +838,4 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
 export const OrchestrationProjectionSnapshotQueryLive = Layer.effect(
   ProjectionSnapshotQuery,
   makeProjectionSnapshotQuery,
-);
+).pipe(Layer.provideMerge(RepositoryIdentityResolverLive));

apps/server/src/project/Layers/RepositoryIdentityResolver.test.ts

@@ -0,0 +1,76 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { expect, it } from "@effect/vitest";
+import { Effect, FileSystem } from "effect";
+
+import { runProcess } from "../../processRunner.ts";
+import { RepositoryIdentityResolver } from "../Services/RepositoryIdentityResolver.ts";
+import { RepositoryIdentityResolverLive } from "./RepositoryIdentityResolver.ts";
+
+const git = (cwd: string, args: ReadonlyArray<string>) =>
+  Effect.promise(() => runProcess("git", ["-C", cwd, ...args]));
+
+it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
+  it.effect("normalizes equivalent GitHub remotes into a stable repository identity", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const cwd = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-repository-identity-test-",
+      });
+
+      yield* git(cwd, ["init"]);
+      yield* git(cwd, ["remote", "add", "origin", "git@github.com:T3Tools/t3code.git"]);
+
+      const resolver = yield* RepositoryIdentityResolver;
+      const identity = yield* resolver.resolve(cwd);
+
+      expect(identity).not.toBeNull();
+      expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
+      expect(identity?.displayName).toBe("T3Tools/t3code");
+      expect(identity?.provider).toBe("github");
+      expect(identity?.owner).toBe("T3Tools");
+      expect(identity?.name).toBe("t3code");
+    }).pipe(Effect.provide(RepositoryIdentityResolverLive)),
+  );
+
+  it.effect("returns null for non-git folders and repos without remotes", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const nonGitDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-repository-identity-non-git-",
+      });
+      const gitDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-repository-identity-no-remote-",
+      });
+
+      yield* git(gitDir, ["init"]);
+
+      const resolver = yield* RepositoryIdentityResolver;
+      const nonGitIdentity = yield* resolver.resolve(nonGitDir);
+      const noRemoteIdentity = yield* resolver.resolve(gitDir);
+
+      expect(nonGitIdentity).toBeNull();
+      expect(noRemoteIdentity).toBeNull();
+    }).pipe(Effect.provide(RepositoryIdentityResolverLive)),
+  );
+
+  it.effect("prefers upstream over origin when both remotes are configured", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const cwd = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-repository-identity-upstream-test-",
+      });
+
+      yield* git(cwd, ["init"]);
+      yield* git(cwd, ["remote", "add", "origin", "git@github.com:julius/t3code.git"]);
+      yield* git(cwd, ["remote", "add", "upstream", "git@github.com:T3Tools/t3code.git"]);
+
+      const resolver = yield* RepositoryIdentityResolver;
+      const identity = yield* resolver.resolve(cwd);
+
+      expect(identity).not.toBeNull();
+      expect(identity?.locator.remoteName).toBe("upstream");
+      expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
+      expect(identity?.displayName).toBe("T3Tools/t3code");
+    }).pipe(Effect.provide(RepositoryIdentityResolverLive)),
+  );
+});