tinker-agent 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-08-31
+
+### Changed
+
+- Store per-workspace runtime state in the global Tinker home instead of inside
+  the project. Sessions (`sessions/<id>/`), background Bash logs (`bash/`),
+  image assets (`assets/images/`), and prompt history now live under
+  `~/.tinker/projects/<workspace-slug-hash>/`, keyed by the workspace's
+  canonical absolute path. Projects no longer grow a `.tinker/` directory.
+  Existing in-project `.tinker/` state is left in place but no longer read.
+- Add `TINKER_HOME` to relocate the global Tinker home directory (default: the
+  OS home directory).
+
 ## [2.2.0] - 2026-08-29
 
 ### Added
@@ -264,7 +277,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.2.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.3.0...HEAD
+[2.3.0]: https://github.com/ishowshao/tinker/releases/tag/v2.3.0
 [2.2.0]: https://github.com/ishowshao/tinker/releases/tag/v2.2.0
 [2.1.0]: https://github.com/ishowshao/tinker/releases/tag/v2.1.0
 [2.0.0]: https://github.com/ishowshao/tinker/releases/tag/v2.0.0

package/README.md

@@ -458,13 +458,22 @@ one-shot `tinker run` command. See
 [`docs/project-custom-slash-commands-design.md`](docs/project-custom-slash-commands-design.md)
 for the full contract.
 
-### Workspace-Local Runtime Data
-
-Tinker keeps private runtime state under `<workspace>/.tinker/`: each session has
-its own SQLite database, event log, and observation log, while image assets and
-Prompt history are stored at the workspace level. These locations are fixed and
-have no public path-override environment variables. MCP server configuration is
-loaded from `<workspace>/.mcp.json`; project slash commands are loaded from
+### Global Runtime Data
+
+Tinker keeps private runtime state in a global home directory instead of inside
+your projects. Each workspace maps to
+`~/.tinker/projects/<workspace-slug-hash>/` — the slug comes from the workspace
+directory name and the hash from its canonical absolute path, so one project
+always resolves to one storage directory even when reached through symlinks.
+That directory holds per-session SQLite databases, event logs, and observation
+logs (`sessions/<id>/`), background Bash task logs (`bash/`), imported image
+assets (`assets/images/`), and prompt history (`prompt-history.jsonl`).
+Workspaces stay clean: no `.tinker/` directory is created inside them.
+
+Set `TINKER_HOME` to relocate the global home (default: the OS home directory).
+Global memory lives in `<home>/.tinker/memory/` and the Chrome bridge host in
+`<home>/.tinker/chrome/`. MCP server configuration is loaded from
+`<workspace>/.mcp.json`; project slash commands are loaded from
 `<workspace>/.tinker.json`.
 
 `Read` has a fixed 262144-byte (256 KiB) content limit per call. A successful
@@ -494,8 +503,9 @@ tinker/
 │   ├── context/       # Context protocol validation, protocol frame construction
 │   └── ids/           # Runtime ID generation (UUID v7)
 ├── docs/              # Design notes and planning documents
-├── .tinker/           # Runtime data (sessions, bash tasks, events)
 └── package.json
+
+Runtime data lives in ~/.tinker/ (sessions, bash tasks, assets), not in the repo.
 ```
 
 ## Design Philosophy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent/runtime-session.ts

@@ -287,6 +287,7 @@ export type CompletedTurnHook = {
 
 type CommonRuntimeSessionInput = {
   workspaceRoot: string;
+  homeRoot?: string;
   modelName: string;
   profileName?: string;
   maxIterations: number;
@@ -341,7 +342,10 @@ export type RuntimeSessionFactoryDependencies = {
     idFactory: RuntimeIdFactory,
   ) => Promise<SessionStore>;
   createLedger: (store: SessionStore, idFactory: RuntimeIdFactory) => SessionLedger;
-  createEventSink: (input: CreateRuntimeSessionInput) => EventSink;
+  createEventSink: (
+    input: CreateRuntimeSessionInput,
+    sessionDirectory: string,
+  ) => EventSink;
   selectShadowPlanning: NonNullable<RunAgentInput["shadowPlanning"]>["select"];
   onShadowPlanningResult?: NonNullable<RunAgentInput["shadowPlanning"]>["onResult"];
   selectContextAutomation: typeof selectContextAutomation;
@@ -407,10 +411,12 @@ const defaultDependencies: RuntimeSessionFactoryDependencies = {
           systemPrompt: input.systemPrompt,
           projectInstruction: input.projectInstruction,
           idFactory,
+          ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         })
       : SessionStore.openExisting({
           workspaceRoot: input.workspaceRoot,
           sessionId: input.selection.sessionId,
+          ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         }),
   createLedger: (store, idFactory) => new SqliteSessionLedger(store, idFactory),
   createEventSink,
@@ -541,7 +547,10 @@ class DefaultRuntimeSession implements RuntimeSession {
     const store = await dependencies.openStore(input, dependencies.idFactory);
     let assetStore: ImageAssetStore;
     try {
-      assetStore = await ImageAssetStore.open({ workspaceRoot: store.workspaceRoot });
+      assetStore = await ImageAssetStore.open({
+        workspaceRoot: store.workspaceRoot,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
+      });
     } catch (error) {
       if (isNewSessionInput(input)) {
         await store
@@ -557,7 +566,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       session = new DefaultRuntimeSession(
         input,
         dependencies,
-        dependencies.createEventSink(input),
+        dependencies.createEventSink(input, store.sessionDirectory),
         dependencies.createObservationBuilder(),
         store,
         assetStore,
@@ -654,6 +663,7 @@ class DefaultRuntimeSession implements RuntimeSession {
 
       session.tooling = dependencies.createTooling({
         workspaceRoot: input.workspaceRoot,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         runtimeSession: session.context,
         historyReader: store.historyReader(),
         imageAssetStore: assetStore,
@@ -2928,21 +2938,19 @@ export async function createRuntimeSession(
   });
 }
 
-function createEventSink(input: CreateRuntimeSessionInput): EventSink {
+function createEventSink(
+  input: CreateRuntimeSessionInput,
+  sessionDirectory: string,
+): EventSink {
   const requiredSinks: EventSink[] = [];
   if (input.persistence !== false) {
-    const basePath = path.join(
-      input.workspaceRoot,
-      ".tinker",
-      "sessions",
-      input.selection.sessionId,
-    );
     requiredSinks.push(
       new JsonlEventLog(
-        input.persistence?.eventLogPath ?? path.join(basePath, "events.jsonl"),
+        input.persistence?.eventLogPath ?? path.join(sessionDirectory, "events.jsonl"),
       ),
       new ObservationTextLog(
-        input.persistence?.observationLogPath ?? path.join(basePath, "observations.md"),
+        input.persistence?.observationLogPath ??
+          path.join(sessionDirectory, "observations.md"),
       ),
     );
   }

package/src/cli/config.ts

@@ -24,6 +24,7 @@ import {
   type ParsedPublicEnvironment,
   type PublicToolingConfig,
 } from "./public-config-contract";
+import { resolveWorkspaceStorageRoot } from "../session/workspace-storage";
 
 export type RunnerConfig = {
   readonly sessionId: SessionId;
@@ -227,17 +228,12 @@ function runnerConfigFromTemplate(
   });
 }
 
-export function eventLogPath(workspaceRoot: string, sessionId: SessionId): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "events.jsonl");
-}
-
-export function observationLogPath(
+export async function promptHistoryPath(
   workspaceRoot: string,
-  sessionId: SessionId,
-): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "observations.md");
-}
-
-export function promptHistoryPath(workspaceRoot: string): string {
-  return path.join(workspaceRoot, ".tinker", "prompt-history.jsonl");
+  homeRoot?: string,
+): Promise<string> {
+  return path.join(
+    await resolveWorkspaceStorageRoot(workspaceRoot, homeRoot),
+    "prompt-history.jsonl",
+  );
 }

package/src/cli/tui-runner.tsx

@@ -160,7 +160,9 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
       config.sessionId,
       projectionStore,
     );
-    const promptHistory = await PromptHistory.load(promptHistoryPath(workspaceRoot));
+    const promptHistory = await PromptHistory.load(
+      await promptHistoryPath(workspaceRoot),
+    );
     const catalog = new SessionCatalog({ workspaceRoot });
 
     const openStoredSession = async (

package/src/image/image-asset-store.ts

@@ -21,6 +21,7 @@ import {
   type ImageAssetId,
   type ImageAssetRef,
 } from "./image-types";
+import { canonicalHomeRoot, workspaceStorageRoot } from "../session/workspace-storage";
 
 const STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const STAGING_PATTERN =
@@ -47,13 +48,18 @@ export class ImageAssetStore {
   static async open(input: {
     workspaceRoot: string;
     onWarning?: (message: string) => void;
+    homeRoot?: string;
   }): Promise<ImageAssetStore> {
     const workspaceRoot = await realpath(input.workspaceRoot);
     const workspaceStat = await stat(workspaceRoot);
     if (!workspaceStat.isDirectory()) {
       throw new Error(`Workspace root is not a directory: ${workspaceRoot}.`);
     }
-    const root = await ensureAssetRoot(workspaceRoot);
+    const storageRoot = workspaceStorageRoot(
+      workspaceRoot,
+      await canonicalHomeRoot(input.homeRoot),
+    );
+    const root = await ensureAssetRoot(storageRoot);
     const store = new ImageAssetStore(workspaceRoot, root, input.onWarning);
     await store.cleanupStagingFiles();
     return store;
@@ -271,9 +277,18 @@ export class ImageAssetStore {
   }
 }
 
-async function ensureAssetRoot(workspaceRoot: string): Promise<string> {
-  let current = workspaceRoot;
-  for (const name of [".tinker", "assets", "images"]) {
+async function ensureAssetRoot(storageRoot: string): Promise<string> {
+  await mkdir(storageRoot, { recursive: true, mode: 0o700 });
+  const storageEntry = await lstat(storageRoot);
+  if (storageEntry.isSymbolicLink() || !storageEntry.isDirectory()) {
+    throw new Error(
+      `Workspace storage root is not a regular directory: ${storageRoot}.`,
+    );
+  }
+  await chmod(storageRoot, 0o700);
+
+  let current = storageRoot;
+  for (const name of ["assets", "images"]) {
     current = path.join(current, name);
     try {
       const entry = await lstat(current);
@@ -288,12 +303,10 @@ async function ensureAssetRoot(workspaceRoot: string): Promise<string> {
       }
       await mkdir(current, { mode: 0o700 });
     }
-    if (name !== ".tinker") {
-      await chmod(current, 0o700);
-    }
+    await chmod(current, 0o700);
   }
   const canonical = await realpath(current);
-  assertContained(workspaceRoot, canonical, "Image asset root");
+  assertContained(storageRoot, canonical, "Image asset root");
   if (canonical !== current) {
     throw new Error("Image asset root is not canonical.");
   }

package/src/memory/contracts.ts

@@ -131,6 +131,12 @@ export type MemoryExtractionDiagnostic = {
   readonly written: number;
   readonly rejected: MemoryExtractionRejectedCounts;
   readonly ms: number;
+  /**
+   * Bounded single-line error detail (message plus cause chain) recorded for
+   * failed and skipped outcomes so provider/parse failures are diagnosable
+   * from the log alone. Absent on success.
+   */
+  readonly detail?: string;
 };
 
 export type MemorySearchDiagnostic = {
@@ -196,6 +202,31 @@ export function boundedMemoryError(error: unknown): string {
   return truncateUtf8(singleLine, 400);
 }
 
+export function boundedMemoryErrorDetail(error: unknown): string {
+  const parts: string[] = [];
+  let current: unknown = error;
+  for (
+    let depth = 0;
+    depth < 4 && current !== undefined && current !== null;
+    depth += 1
+  ) {
+    const raw =
+      current instanceof Error
+        ? current.message
+        : typeof current === "string" ||
+            typeof current === "number" ||
+            typeof current === "boolean"
+          ? String(current)
+          : "unknown non-error cause";
+    const singleLine = raw.replaceAll(/\s+/g, " ").trim();
+    if (singleLine !== "" && !parts.includes(singleLine)) {
+      parts.push(singleLine);
+    }
+    current = current instanceof Error ? current.cause : undefined;
+  }
+  return truncateUtf8(parts.join(" | ") || "unknown memory error", 400);
+}
+
 export function truncateUtf8(value: string, maxBytes: number): string {
   if (Buffer.byteLength(value, "utf8") <= maxBytes) {
     return value;

package/src/memory/memory-coordinator.ts

@@ -25,6 +25,7 @@ import {
   MEMORY_SEARCH_LIMIT,
   MEMORY_SEARCH_TOOL_NAME,
   MemoryError,
+  boundedMemoryErrorDetail,
   truncateUtf8,
   type MemoryEmbeddingConfig,
   type MemoryExtractionDiagnostic,
@@ -248,6 +249,7 @@ export class MemoryCoordinator implements CompletedTurnHook {
             turnId: task.turnId,
             inputTokens,
             ms: elapsedMs(startedAt),
+            detail: boundedMemoryErrorDetail(error),
           }),
         );
         return;
@@ -272,6 +274,7 @@ export class MemoryCoordinator implements CompletedTurnHook {
           returned,
           rejected,
           ms: elapsedMs(startedAt),
+          detail: boundedMemoryErrorDetail(error),
         }),
       );
       return;
@@ -343,6 +346,7 @@ export class MemoryCoordinator implements CompletedTurnHook {
           returned,
           rejected,
           ms: elapsedMs(startedAt),
+          detail: boundedMemoryErrorDetail(error),
         }),
       );
       return;
@@ -401,6 +405,7 @@ export class MemoryCoordinator implements CompletedTurnHook {
           returned,
           rejected,
           ms: elapsedMs(startedAt),
+          detail: boundedMemoryErrorDetail(error),
         }),
       );
     }
@@ -663,6 +668,7 @@ function extractionDiagnostic(input: {
   readonly returned?: number;
   readonly written?: number;
   readonly rejected?: MemoryExtractionRejectedCounts;
+  readonly detail?: string;
 }): MemoryExtractionDiagnostic {
   return Object.freeze({
     at: input.clock(),
@@ -676,6 +682,7 @@ function extractionDiagnostic(input: {
     written: input.written ?? 0,
     rejected: input.rejected ?? emptyRejectedCounts(),
     ms: input.ms,
+    ...(input.detail === undefined ? {} : { detail: input.detail }),
   });
 }
 

package/src/memory/memory-extractor.ts

@@ -13,6 +13,7 @@ import {
   MAX_MEMORY_SUMMARY_BYTES,
   MAX_MEMORY_TEXT_BYTES,
   MemoryError,
+  truncateUtf8,
 } from "./contracts";
 
 const EXTRACTION_SYSTEM_PROMPT = `You record one faithful historical summary of a completed coding-agent turn. Your job is to record what happened, not to judge what deserves long-term storage.
@@ -35,6 +36,10 @@ Rules:
 - Do not copy long passages. Keep both fields dense and within their byte budgets.
 `;
 
+const MEMORY_EXTRACTION_RESPONSE_FORMAT = Object.freeze({
+  type: "json_object" as const,
+});
+
 export type MemoryExtractionCandidate = {
   readonly text: string;
   readonly summary: string;
@@ -102,7 +107,14 @@ export class MemoryExtractor {
     let prepared: PreparedModelRequest;
     let inputTokens: number;
     try {
-      prepared = this.model.prepare({ messages, tools: [] });
+      prepared = this.model.prepare({
+        messages,
+        tools: [],
+        // Provider-enforced JSON mode: prompt wording alone lets the model
+        // wrap the record in markdown fences or prose, which previously
+        // surfaced as extraction_output_invalid failures and dropped memories.
+        responseFormat: MEMORY_EXTRACTION_RESPONSE_FORMAT,
+      });
       const rawInputTokens = estimatePromptSegments(
         prepared.promptSegments,
       ).totalTokens;
@@ -160,6 +172,15 @@ export class MemoryExtractor {
   }
 }
 
+function outputPreview(content: string | null | undefined): string {
+  if (typeof content !== "string" || content.trim() === "") {
+    return "(empty)";
+  }
+  const singleLine = content.replaceAll(/\s+/g, " ").trim();
+  const preview = truncateUtf8(singleLine, 160);
+  return preview === singleLine ? preview : `${preview}…`;
+}
+
 function parseExtractionOutput(message: {
   readonly content?: string | null;
   readonly toolCalls?: readonly unknown[];
@@ -169,7 +190,7 @@ function parseExtractionOutput(message: {
     (message.toolCalls !== undefined && message.toolCalls.length > 0)
   ) {
     throw new MemoryExtractionOutputError(
-      "Memory extraction response must contain only JSON text.",
+      `Memory extraction response must contain only JSON text. output=${outputPreview(message.content)}`,
       0,
     );
   }
@@ -179,7 +200,7 @@ function parseExtractionOutput(message: {
     value = JSON.parse(message.content);
   } catch (error) {
     throw new MemoryExtractionOutputError(
-      "Memory extraction response is not valid JSON.",
+      `Memory extraction response is not valid JSON. output=${outputPreview(message.content)}`,
       0,
       0,
       { cause: error },
@@ -187,7 +208,7 @@ function parseExtractionOutput(message: {
   }
   if (!isRecord(value)) {
     throw new MemoryExtractionOutputError(
-      "Memory extraction response must be an object.",
+      `Memory extraction response must be an object. output=${outputPreview(message.content)}`,
       0,
     );
   }
@@ -200,7 +221,7 @@ function parseExtractionOutput(message: {
     typeof value.summary !== "string"
   ) {
     throw new MemoryExtractionOutputError(
-      'Memory extraction response must contain only "text" and "summary" strings.',
+      `Memory extraction response must contain only "text" and "summary" strings. output=${outputPreview(message.content)}`,
       0,
     );
   }

package/src/model/fake-model-client.ts

@@ -86,6 +86,7 @@ export class FakeModelClient implements ModelClient {
         requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
         inputModalities: this.inputModalities,
         toolResultModalities: this.toolResultModalities,
+        responseFormat: input.responseFormat?.type ?? null,
       }),
     );
     const prepared: PreparedModelRequest = Object.freeze({
@@ -96,6 +97,9 @@ export class FakeModelClient implements ModelClient {
         tools: Object.freeze([...input.tools]),
         maxTokens: this.options.contextBudget.requestMaxOutputTokens,
         ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+        ...(input.responseFormat === undefined
+          ? {}
+          : { responseFormat: input.responseFormat }),
       }),
       promptSegments: Object.freeze([...toolSegments, ...messageSegments]),
       requestConfigHash,
@@ -111,6 +115,9 @@ export class FakeModelClient implements ModelClient {
     this.preparedInputs.set(prepared, {
       messages: [...input.messages],
       tools: [...input.tools],
+      ...(input.responseFormat === undefined
+        ? {}
+        : { responseFormat: input.responseFormat }),
     });
     return prepared;
   }

package/src/model/model-client.ts

@@ -103,9 +103,20 @@ export type ModelRequestOptions = {
   };
 };
 
+/**
+ * Provider-enforced structured output for a single request. Distinct from
+ * prompt-level instructions: the provider constrains the decoded response to
+ * be a valid JSON object, so callers still validate shape but no longer fight
+ * markdown fences or surrounding prose.
+ */
+export type ModelResponseFormat = {
+  readonly type: "json_object";
+};
+
 export type ModelRequestInput = {
   messages: AgentMessage[];
   tools: ToolDefinition[];
+  responseFormat?: ModelResponseFormat;
 };
 
 export type PreparedPromptSegmentKind =

package/src/model/openai-chat-model-client.ts

@@ -107,6 +107,9 @@ export class OpenAIChatModelClient implements ModelClient {
       messages,
       ...(tools === undefined ? {} : { tools, tool_choice: "auto" as const }),
       ...(reasoningEffort === undefined ? {} : { reasoning_effort: reasoningEffort }),
+      ...(input.responseFormat === undefined
+        ? {}
+        : { response_format: { type: input.responseFormat.type } }),
       max_completion_tokens: this.options.contextBudget.requestMaxOutputTokens,
       ...(this.stream
         ? {
@@ -147,7 +150,10 @@ export class OpenAIChatModelClient implements ModelClient {
         stream: this.stream,
         inputModalities: this.inputModalities,
         toolResultModalities: this.toolResultModalities,
-        requestPolicy: { toolChoice: "auto" },
+        requestPolicy: {
+          toolChoice: "auto",
+          responseFormat: input.responseFormat?.type ?? null,
+        },
         imagePolicy: {
           version: IMAGE_INPUT_POLICY_VERSION,
           ...IMAGE_INPUT_POLICY,

package/src/model/openai-responses-model-client.ts

@@ -111,6 +111,9 @@ export class OpenAIResponsesModelClient implements ModelClient {
         : { reasoning: { effort: reasoningEffort } }),
       max_output_tokens: this.options.contextBudget.requestMaxOutputTokens,
       store: false as const,
+      ...(input.responseFormat === undefined
+        ? {}
+        : { text: { format: { type: input.responseFormat.type } } }),
       ...(this.stream ? { stream: true as const } : {}),
     });
     const toolSegments = (tools ?? []).map(
@@ -148,7 +151,11 @@ export class OpenAIResponsesModelClient implements ModelClient {
         stream: this.stream,
         inputModalities: this.inputModalities,
         toolResultModalities: this.toolResultModalities,
-        requestPolicy: { store: false, toolChoice: "auto" },
+        requestPolicy: {
+          store: false,
+          toolChoice: "auto",
+          responseFormat: input.responseFormat?.type ?? null,
+        },
         imagePolicy: {
           version: IMAGE_INPUT_POLICY_VERSION,
           ...IMAGE_INPUT_POLICY,

package/src/session/resume-projection.ts

@@ -1,4 +1,3 @@
-import path from "node:path";
 import { realpath } from "node:fs/promises";
 import { Database } from "bun:sqlite";
 import type { ToolCall } from "../agent/types";
@@ -24,7 +23,11 @@ import {
 } from "../tui/tui-projection-policy";
 import { SessionError } from "./session-errors";
 import { verifySessionSchema } from "./session-schema";
-import { decodeStoredToolCalls, decodeStoredToolRawResult } from "./session-store";
+import {
+  decodeStoredToolCalls,
+  decodeStoredToolRawResult,
+  resolveSessionDatabasePath,
+} from "./session-store";
 import {
   MAX_TIMELINE_PROMPT_CODE_POINTS,
   projectUserMessage,
@@ -46,17 +49,16 @@ export class ResumeProjectionReader {
     sessionId: SessionId;
     modelName: string;
     policy?: TuiProjectionPolicy;
+    homeRoot?: string;
   }): Promise<TuiProjectionState> {
     const policy = validateTuiProjectionPolicy(
       input.policy ?? defaultTuiProjectionPolicy,
     );
     const workspaceRoot = await realpath(input.workspaceRoot);
-    const databasePath = path.join(
+    const databasePath = await resolveSessionDatabasePath(
       workspaceRoot,
-      ".tinker",
-      "sessions",
       input.sessionId,
-      "session.sqlite",
+      input.homeRoot,
     );
     const database = new Database(databasePath, {
       readonly: true,

package/src/session/session-catalog.ts

@@ -6,6 +6,7 @@ import { SessionError } from "./session-errors";
 import { inspectSessionLock } from "./session-lock";
 import { SessionStore } from "./session-store";
 import { verifyReadableSessionSchema } from "./session-schema";
+import { canonicalHomeRoot, workspaceStorageRoot } from "./workspace-storage";
 
 export type SessionSummary = {
   sessionId: SessionId;
@@ -28,9 +29,22 @@ export type SessionSummary = {
 
 export class SessionCatalog {
   private readonly workspaceRootPromise: Promise<string>;
+  private readonly sessionsRootPromise: Promise<string>;
 
-  constructor(private readonly input: { workspaceRoot: string; limit?: number }) {
+  constructor(
+    private readonly input: {
+      workspaceRoot: string;
+      limit?: number;
+      homeRoot?: string;
+    },
+  ) {
     this.workspaceRootPromise = realpath(input.workspaceRoot);
+    this.sessionsRootPromise = this.workspaceRootPromise.then(async (workspaceRoot) =>
+      path.join(
+        workspaceStorageRoot(workspaceRoot, await canonicalHomeRoot(input.homeRoot)),
+        "sessions",
+      ),
+    );
   }
 
   async list(currentSessionId?: SessionId): Promise<readonly SessionSummary[]> {
@@ -44,7 +58,7 @@ export class SessionCatalog {
 
   private async scan(currentSessionId?: SessionId): Promise<SessionSummary[]> {
     const workspaceRoot = await this.workspaceRootPromise;
-    const sessionsRoot = path.join(workspaceRoot, ".tinker", "sessions");
+    const sessionsRoot = await this.sessionsRootPromise;
     let entries;
     try {
       entries = await readdir(sessionsRoot, { withFileTypes: true });
@@ -87,7 +101,7 @@ export class SessionCatalog {
     currentSessionId?: SessionId,
   ): Promise<SessionSummary> {
     const workspaceRoot = await this.workspaceRootPromise;
-    const directory = path.join(workspaceRoot, ".tinker", "sessions", sessionId);
+    const directory = path.join(await this.sessionsRootPromise, sessionId);
     return readSummary(directory, sessionId, workspaceRoot, currentSessionId);
   }
 
@@ -105,6 +119,7 @@ export class SessionCatalog {
       workspaceRoot,
       sessionId,
       allowIncomplete: true,
+      ...(this.input.homeRoot === undefined ? {} : { homeRoot: this.input.homeRoot }),
     });
     try {
       await store.deleteFromDisk();

package/src/session/session-last-response-reader.ts

@@ -4,22 +4,26 @@ import { contentHash } from "../context/protocol-frame";
 import type { SessionId } from "../ids/runtime-id";
 import { SessionError, sessionOpenError, sessionReadError } from "./session-errors";
 import { verifySessionSchema } from "./session-schema";
-import { decodeStoredToolCalls, sessionDatabasePath } from "./session-store";
+import { decodeStoredToolCalls, resolveSessionDatabasePath } from "./session-store";
 
 const OPERATION = "read_last_assistant_response";
 
 export async function readLastAssistantResponse(input: {
   workspaceRoot: string;
   sessionId: SessionId;
+  homeRoot?: string;
 }): Promise<string | undefined> {
   const workspaceRoot = await realpath(input.workspaceRoot);
   let database: Database;
   try {
-    database = new Database(sessionDatabasePath(workspaceRoot, input.sessionId), {
-      readonly: true,
-      strict: true,
-      safeIntegers: true,
-    });
+    database = new Database(
+      await resolveSessionDatabasePath(workspaceRoot, input.sessionId, input.homeRoot),
+      {
+        readonly: true,
+        strict: true,
+        safeIntegers: true,
+      },
+    );
   } catch (error) {
     throw sessionOpenError(OPERATION, input.sessionId, error);
   }

package/src/session/session-store.ts

@@ -34,6 +34,11 @@ import {
 } from "../model/model-client";
 import type { ToolDefinition, ToolRawResult } from "../tools/types";
 import { sha256, stableJsonStringify } from "../model/model-request-preflight";
+import {
+  canonicalHomeRoot,
+  resolveWorkspaceStorageRoot,
+  workspaceStorageRoot,
+} from "./workspace-storage";
 import {
   ContextProtocolError,
   ContextProtocolValidator,
@@ -418,6 +423,7 @@ export type CreateNewSessionStoreInput = {
   projectInstruction?: ProjectInstructionManifest;
   idFactory: RuntimeIdFactory;
   clock?: () => string;
+  homeRoot?: string;
 };
 
 export type OpenSessionStoreInput = {
@@ -425,6 +431,7 @@ export type OpenSessionStoreInput = {
   sessionId: SessionId;
   clock?: () => string;
   allowIncomplete?: boolean;
+  homeRoot?: string;
 };
 
 export class SessionStore implements SessionLedgerCommitter {
@@ -447,6 +454,7 @@ export class SessionStore implements SessionLedgerCommitter {
       sessionDirectory: string;
       databasePath: string;
       clock: () => string;
+      homeRoot?: string;
     },
   ) {
     this.sessionId = input.sessionId;
@@ -454,14 +462,17 @@ export class SessionStore implements SessionLedgerCommitter {
     this.sessionDirectory = input.sessionDirectory;
     this.databasePath = input.databasePath;
     this.clock = input.clock;
+    this.homeRoot = input.homeRoot;
   }
 
+  private readonly homeRoot?: string;
+
   private readonly clock: () => string;
 
   static async createNew(input: CreateNewSessionStoreInput): Promise<SessionStore> {
     const clock = input.clock ?? (() => new Date().toISOString());
     const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
-    const sessionsRoot = await ensureSessionsRoot(workspaceRoot);
+    const sessionsRoot = await ensureSessionsRoot(workspaceRoot, input.homeRoot);
     const sessionDirectory = safeSessionDirectory(sessionsRoot, input.sessionId);
     try {
       await mkdir(sessionDirectory, { mode: 0o700 });
@@ -540,6 +551,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory,
         databasePath,
         clock,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
       });
       await store.correctDatabaseModes();
       store.validateCreatingState();
@@ -558,7 +570,10 @@ export class SessionStore implements SessionLedgerCommitter {
   static async openExisting(input: OpenSessionStoreInput): Promise<SessionStore> {
     const clock = input.clock ?? (() => new Date().toISOString());
     const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
-    const sessionsRoot = path.join(workspaceRoot, ".tinker", "sessions");
+    const sessionsRoot = path.join(
+      workspaceStorageRoot(workspaceRoot, await canonicalHomeRoot(input.homeRoot)),
+      "sessions",
+    );
     await validateSessionsRoot(sessionsRoot, input.sessionId);
     const sessionDirectory = safeSessionDirectory(sessionsRoot, input.sessionId);
     await validateSecureDirectory(sessionDirectory, input.sessionId);
@@ -593,6 +608,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory,
         databasePath,
         clock,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
       });
       store.recallIndexRebuilt = recallIndexContractUpgraded;
       const meta = store.readMeta();
@@ -2366,7 +2382,10 @@ export class SessionStore implements SessionLedgerCommitter {
     if (distinct.size === 0) {
       return;
     }
-    const store = await ImageAssetStore.open({ workspaceRoot: this.workspaceRoot });
+    const store = await ImageAssetStore.open({
+      workspaceRoot: this.workspaceRoot,
+      ...(this.homeRoot === undefined ? {} : { homeRoot: this.homeRoot }),
+    });
     for (const asset of distinct.values()) {
       await store.verify(asset);
     }
@@ -2670,6 +2689,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory: stagingDirectory,
         databasePath: stagingDatabasePath,
         clock: this.clock,
+        ...(this.homeRoot === undefined ? {} : { homeRoot: this.homeRoot }),
       });
       clonedStore.validateAll({ allowOpenTail: false });
       await clonedStore.verifyImageAssetFiles();
@@ -3802,11 +3822,17 @@ function normalizeInputModalities(
   );
 }
 
-export function sessionDatabasePath(
+export async function resolveSessionDatabasePath(
   workspaceRoot: string,
   sessionId: SessionId,
-): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "session.sqlite");
+  homeRoot?: string,
+): Promise<string> {
+  return path.join(
+    await resolveWorkspaceStorageRoot(workspaceRoot, homeRoot),
+    "sessions",
+    sessionId,
+    "session.sqlite",
+  );
 }
 
 function insertFrame(database: Database, frame: ProtocolFrame): void {
@@ -6081,8 +6107,14 @@ async function canonicalWorkspaceRoot(workspaceRoot: string): Promise<string> {
   return realpath(workspaceRoot);
 }
 
-async function ensureSessionsRoot(workspaceRoot: string): Promise<string> {
-  const tinkerRoot = path.join(workspaceRoot, ".tinker");
+async function ensureSessionsRoot(
+  workspaceRoot: string,
+  homeRoot?: string,
+): Promise<string> {
+  const tinkerRoot = workspaceStorageRoot(
+    workspaceRoot,
+    await canonicalHomeRoot(homeRoot),
+  );
   const sessionsRoot = path.join(tinkerRoot, "sessions");
   await mkdir(sessionsRoot, { recursive: true, mode: 0o700 });
   await validateSessionsRoot(sessionsRoot);

package/src/session/workspace-storage.ts

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const TINKER_HOME_DIR = ".tinker";
+const PROJECTS_DIR = "projects";
+const SLUG_MAX_LENGTH = 24;
+const HASH_HEX_LENGTH = 8;
+const FALLBACK_SLUG = "project";
+
+export const TINKER_HOME_ENV = "TINKER_HOME";
+
+/**
+ * Base directory for global Tinker state. TINKER_HOME overrides the OS home
+ * directory; tests and the PTY harness use it to isolate state.
+ */
+export function defaultHomeRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env[TINKER_HOME_ENV]?.trim();
+  return override === undefined || override === "" ? os.homedir() : override;
+}
+
+/**
+ * Stable directory name for one workspace inside the global Tinker home, e.g.
+ * "tinker-a1b2c3d4". The slug is decorative; the hash suffix over the
+ * canonical workspace path provides uniqueness.
+ */
+export function workspaceStorageDirectoryName(canonicalWorkspaceRoot: string): string {
+  const slug = slugify(path.basename(canonicalWorkspaceRoot));
+  const hash = createHash("sha256")
+    .update(canonicalWorkspaceRoot)
+    .digest("hex")
+    .slice(0, HASH_HEX_LENGTH);
+  return `${slug}-${hash}`;
+}
+
+/**
+ * Storage root for one canonical workspace root under a canonical home root:
+ * <home>/.tinker/projects/<slug-hash>. Both inputs must already be canonical
+ * (see resolveWorkspaceStorageRoot for the resolving variant).
+ */
+export function workspaceStorageRoot(
+  canonicalWorkspaceRoot: string,
+  canonicalHomeRoot: string,
+): string {
+  return path.join(
+    canonicalHomeRoot,
+    TINKER_HOME_DIR,
+    PROJECTS_DIR,
+    workspaceStorageDirectoryName(canonicalWorkspaceRoot),
+  );
+}
+
+/** Canonical (symlink-resolved) home root used for global Tinker state. */
+export async function canonicalHomeRoot(
+  homeRoot: string = defaultHomeRoot(),
+): Promise<string> {
+  return realpath(homeRoot);
+}
+
+/**
+ * Resolves the per-workspace storage root under the global Tinker home. Both
+ * the workspace and the home root are canonicalized so a project reached
+ * through different symlinked paths maps to a single storage directory.
+ */
+export async function resolveWorkspaceStorageRoot(
+  workspaceRoot: string,
+  homeRoot: string = defaultHomeRoot(),
+): Promise<string> {
+  return workspaceStorageRoot(
+    await realpath(workspaceRoot),
+    await canonicalHomeRoot(homeRoot),
+  );
+}
+
+function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, SLUG_MAX_LENGTH)
+    .replace(/-+$/, "");
+  return slug === "" ? FALLBACK_SLUG : slug;
+}

package/src/tools/bash-task.ts

@@ -20,6 +20,7 @@ import {
   TERMINAL_SCREEN_ROWS,
   type TerminalScreen,
 } from "./terminal-screen";
+import { resolveWorkspaceStorageRoot } from "../session/workspace-storage";
 
 export type ShellTaskStatus =
   | "running"
@@ -112,6 +113,7 @@ export type ShellTaskManagerOptions = {
   cwdState: CwdState;
   runtimeSession: RuntimeSessionContext;
   stopGraceMs?: number;
+  homeRoot?: string;
 };
 
 const defaultStopGraceMs = 2_000;
@@ -121,6 +123,7 @@ export class ShellTaskManager {
   private readonly stopGraceMs: number;
   private acceptingTasks = true;
   private shutdownPromise?: Promise<ShutdownResult>;
+  private bashDirectoryPromise?: Promise<string>;
 
   constructor(private readonly options: ShellTaskManagerOptions) {
     this.stopGraceMs = options.stopGraceMs ?? defaultStopGraceMs;
@@ -129,6 +132,14 @@ export class ShellTaskManager {
     }
   }
 
+  private bashDirectory(): Promise<string> {
+    this.bashDirectoryPromise ??= resolveWorkspaceStorageRoot(
+      this.options.workspaceRoot,
+      this.options.homeRoot,
+    ).then((storageRoot) => path.join(storageRoot, "bash"));
+    return this.bashDirectoryPromise;
+  }
+
   async start(input: {
     command: string;
     description: string;
@@ -140,18 +151,9 @@ export class ShellTaskManager {
     }
 
     const id = createUuidV7();
-    const outputFilePath = path.join(
-      this.options.workspaceRoot,
-      ".tinker",
-      "bash",
-      `${id}.log`,
-    );
-    const cwdFilePath = path.join(
-      this.options.workspaceRoot,
-      ".tinker",
-      "bash",
-      `${id}.cwd`,
-    );
+    const bashDirectory = await this.bashDirectory();
+    const outputFilePath = path.join(bashDirectory, `${id}.log`);
+    const cwdFilePath = path.join(bashDirectory, `${id}.cwd`);
     await ensureEmptyFile(cwdFilePath);
 
     const output = await TaskOutput.create(outputFilePath);

package/src/tools/registry.ts

@@ -153,6 +153,7 @@ export function createDefaultTooling(options: {
   workspaceRoot: string;
   runtimeSession: RuntimeSessionContext;
   historyReader: SessionHistoryReader;
+  homeRoot?: string;
   maxReadContentBytes?: number;
   exaApiKey?: string;
   webFetchRefiner?: Refiner;
@@ -187,6 +188,7 @@ export function createDefaultTooling(options: {
     cwdState,
     runtimeSession,
     stopGraceMs: options.taskStopGraceMs,
+    ...(options.homeRoot === undefined ? {} : { homeRoot: options.homeRoot }),
   });
 
   registry.register(