@ai-sdk/harness 1.0.122 → 1.0.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.122",
+  "version": "1.0.123",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.18",
-    "@ai-sdk/provider-utils": "5.0.46",
-    "ai": "7.0.112"
+    "@ai-sdk/provider-utils": "5.0.47",
+    "ai": "7.0.113"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.112",
+    "@ai-sdk/otel": "1.0.113",
     "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",

package/src/agent/harness-agent.ts

@@ -1,10 +1,11 @@
 import { HarnessCapabilityUnsupportedError } from '../errors/harness-capability-unsupported-error';
-import type {
-  HarnessV1,
-  HarnessV1BuiltinToolFiltering,
-  HarnessV1JSONSchema,
-  HarnessV1NetworkSandboxSession,
-  HarnessV1ResponseFormat,
+import {
+  harnessStateDirectoryPath,
+  type HarnessV1,
+  type HarnessV1BuiltinToolFiltering,
+  type HarnessV1JSONSchema,
+  type HarnessV1NetworkSandboxSession,
+  type HarnessV1ResponseFormat,
 } from '../v1';
 import {
   asArray,
@@ -68,6 +69,7 @@ import {
 } from './internal/permission-mode';
 import { resolveHarnessAgentToolFiltering } from './internal/tool-filtering';
 import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
+import { resolveSandboxHomeDir } from '../utils/sandbox-home-dir';
 import { getRestrictedSandboxSession } from '../utils/get-restricted-sandbox-session';
 import type { HarnessAgentLifecycleCallbacks } from './internal/turn-telemetry';
 
@@ -402,7 +404,14 @@ export class HarnessAgent<
             session: toolSafeSandboxSession,
             recipe,
             identity: recipeIdentity,
-            defaultWorkingDirectory,
+            // Harness infrastructure always lives under the sandbox's own
+            // HOME, never the session's working directory.
+            stateDirectory: harnessStateDirectoryPath({
+              sandboxHomeDir: await resolveSandboxHomeDir({
+                sandbox: toolSafeSandboxSession,
+                abortSignal,
+              }),
+            }),
             abortSignal,
           });
         } catch (err) {
@@ -455,8 +464,14 @@ export class HarnessAgent<
               session: resumedSandboxSession.restricted(),
               recipe,
               identity: recipeIdentity,
-              defaultWorkingDirectory:
-                resumedSandboxSession.defaultWorkingDirectory,
+              // Harness infrastructure always lives under the sandbox's own
+              // HOME, never the working directory.
+              stateDirectory: harnessStateDirectoryPath({
+                sandboxHomeDir: await resolveSandboxHomeDir({
+                  sandbox: resumedSandboxSession,
+                  abortSignal,
+                }),
+              }),
               abortSignal,
             });
           } catch (err) {
@@ -503,8 +518,14 @@ export class HarnessAgent<
               session: createdSandboxSession.restricted(),
               recipe: sandboxBootstrapPlan.recipe,
               identity: sandboxBootstrapPlan.recipeIdentity,
-              defaultWorkingDirectory:
-                createdSandboxSession.defaultWorkingDirectory,
+              // Harness infrastructure always lives under the sandbox's own
+              // HOME, never the working directory.
+              stateDirectory: harnessStateDirectoryPath({
+                sandboxHomeDir: await resolveSandboxHomeDir({
+                  sandbox: createdSandboxSession,
+                  abortSignal,
+                }),
+              }),
               abortSignal,
             });
           } catch (err) {
@@ -877,7 +898,6 @@ export class HarnessAgent<
         };
       }
     }
-    return undefined;
   }
 
   /*

package/src/agent/internal/bootstrap-recipe.ts

@@ -1,6 +1,6 @@
 import { posix } from 'node:path';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
-import type { HarnessV1Bootstrap } from '../../v1';
+import { harnessStateDirectoryPath, type HarnessV1Bootstrap } from '../../v1';
 
 /**
  * Version of the bootstrap recipe shape itself. Bump to force every existing
@@ -10,7 +10,9 @@ export const BOOTSTRAP_SCHEMA_VERSION = 1;
 
 /**
  * Deterministic 16-char hex identity derived from the recipe's content
- * (harnessId, bootstrapDir, file paths + contents, commands, schema version).
+ * (harness state directory, harnessId, bootstrapDir, file paths + contents,
+ * commands, schema version). The sandbox's concrete HOME is unavailable until
+ * creation, so the directory is hashed with a symbolic HOME prefix.
  * Two adapters with equivalent recipes produce the same identity; any
  * content change produces a different identity.
  *
@@ -27,6 +29,7 @@ export async function hashHarnessBootstrap(
     chunks.push(encoder.encode('\0'));
   };
 
+  pushString(harnessStateDirectoryPath({ sandboxHomeDir: '$HOME' }));
   pushString(recipe.harnessId);
   pushString(recipe.bootstrapDir);
 
@@ -66,16 +69,16 @@ export async function hashHarnessBootstrap(
 export function bootstrapMarkerPath({
   recipe,
   identity,
-  defaultWorkingDirectory,
+  stateDirectory,
 }: {
   recipe: HarnessV1Bootstrap;
   identity: string;
-  defaultWorkingDirectory: string;
+  stateDirectory: string;
 }): string {
   return posix.join(
     resolveBootstrapPath({
       path: recipe.bootstrapDir,
-      defaultWorkingDirectory,
+      stateDirectory,
     }),
     `.bootstrap-${identity}.ok`,
   );
@@ -95,19 +98,19 @@ export async function applyBootstrapRecipe({
   session,
   recipe,
   identity,
-  defaultWorkingDirectory,
+  stateDirectory,
   abortSignal,
 }: {
   session: SandboxSession;
   recipe: HarnessV1Bootstrap;
   identity: string;
-  defaultWorkingDirectory: string;
+  stateDirectory: string;
   abortSignal?: AbortSignal;
 }): Promise<void> {
   const markerPath = bootstrapMarkerPath({
     recipe,
     identity,
-    defaultWorkingDirectory,
+    stateDirectory,
   });
 
   const existingMarker = await session.readTextFile({
@@ -120,11 +123,10 @@ export async function applyBootstrapRecipe({
 
   const bootstrapDir = resolveBootstrapPath({
     path: recipe.bootstrapDir,
-    defaultWorkingDirectory,
+    stateDirectory,
   });
   const mkdirResult = await session.run({
     command: 'mkdir -p "$BOOTSTRAP_DIR"',
-    workingDirectory: defaultWorkingDirectory,
     env: { BOOTSTRAP_DIR: bootstrapDir },
     abortSignal,
   });
@@ -138,7 +140,7 @@ export async function applyBootstrapRecipe({
     await session.writeTextFile({
       path: resolveBootstrapPath({
         path: file.path,
-        defaultWorkingDirectory,
+        stateDirectory,
       }),
       content: file.content,
       abortSignal,
@@ -167,12 +169,10 @@ export async function applyBootstrapRecipe({
 
 function resolveBootstrapPath({
   path,
-  defaultWorkingDirectory,
+  stateDirectory,
 }: {
   path: string;
-  defaultWorkingDirectory: string;
+  stateDirectory: string;
 }): string {
-  return posix.isAbsolute(path)
-    ? path
-    : posix.resolve(defaultWorkingDirectory, path);
+  return posix.isAbsolute(path) ? path : posix.resolve(stateDirectory, path);
 }

package/src/agent/internal/harness-stream-text-result.ts

@@ -853,10 +853,8 @@ export class HarnessStreamTextResult<
         this.currentStepContent.push({
           ...(part as object),
         } as ContentPart<TOOLS>);
-        return;
       default:
-        // Boundary, raw, error, and finish parts are not ContentParts.
-        return;
+      // Boundary, raw, error, and finish parts are not ContentParts.
     }
   }
 }

package/src/agent/internal/sandbox-bootstrap.ts

@@ -1,7 +1,9 @@
 import { posix } from 'node:path';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
-import type { HarnessV1Bootstrap } from '../../v1';
+import { harnessStateDirectoryPath, type HarnessV1Bootstrap } from '../../v1';
+import { encodeHarnessPathSegment } from '../../v1/harness-session-data-directory-path';
 import { resolveSandboxDefaultWorkingDirectory } from '../../utils/resolve-sandbox-default-working-directory';
+import { resolveSandboxHomeDir } from '../../utils/sandbox-home-dir';
 import type { HarnessAgentSandboxConfig } from '../harness-agent-settings';
 import { applyBootstrapRecipe, hashHarnessBootstrap } from './bootstrap-recipe';
 
@@ -78,7 +80,9 @@ export function resolveSessionWorkDir({
 }): string {
   return joinSandboxPath({
     base: defaultWorkingDirectory,
-    path: workDir ?? `${harnessId}-${sessionId}`,
+    path:
+      workDir ??
+      `${encodeHarnessPathSegment(harnessId)}-${encodeHarnessPathSegment(sessionId)}`,
   });
 }
 
@@ -147,25 +151,35 @@ export async function runSandboxBootstrap({
 }): Promise<void> {
   if (recipe == null && onBootstrap == null) return;
 
-  const resolvedDefaultWorkingDirectory =
-    defaultWorkingDirectory ??
-    (await resolveSandboxDefaultWorkingDirectory({
-      sandboxSession: session,
-      abortSignal,
-    }));
-
   if (recipe != null && recipeIdentity != null) {
     await applyBootstrapRecipe({
       session,
       recipe,
       identity: recipeIdentity,
-      defaultWorkingDirectory: resolvedDefaultWorkingDirectory,
+      // Harness infrastructure always lives under the sandbox's own HOME,
+      // never the working directory resolved below for the caller's own
+      // `onBootstrap` hook. Resolved directly from `session` — this runs
+      // from a provider's `onFirstCreate`, before a
+      // `HarnessV1NetworkSandboxSession` even exists.
+      stateDirectory: harnessStateDirectoryPath({
+        sandboxHomeDir: await resolveSandboxHomeDir({
+          sandbox: session,
+          abortSignal,
+        }),
+      }),
       abortSignal,
     });
   }
 
   if (onBootstrap == null) return;
 
+  const resolvedDefaultWorkingDirectory =
+    defaultWorkingDirectory ??
+    (await resolveSandboxDefaultWorkingDirectory({
+      sandboxSession: session,
+      abortSignal,
+    }));
+
   const bootstrapWorkDir =
     workDir == null
       ? resolvedDefaultWorkingDirectory

package/src/agent/prepare-harness-sandbox-template.ts

@@ -1,4 +1,9 @@
-import type { HarnessV1Bootstrap, HarnessV1SandboxProvider } from '../v1';
+import {
+  harnessStateDirectoryPath,
+  type HarnessV1Bootstrap,
+  type HarnessV1SandboxProvider,
+} from '../v1';
+import { resolveSandboxHomeDir } from '../utils/sandbox-home-dir';
 import type { HarnessAgentAdapter } from './harness-agent-types';
 import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
 import { applyBootstrapRecipe } from './internal/bootstrap-recipe';
@@ -58,11 +63,19 @@ export async function prepareHarnessSandboxTemplate(options: {
   // general harness utility, not for a concrete agent.
   try {
     if (bootstrapPlan.recipe != null && bootstrapPlan.recipeIdentity != null) {
+      const restrictedSession = sandboxSession.restricted();
       await applyBootstrapRecipe({
-        session: sandboxSession.restricted(),
+        session: restrictedSession,
         recipe: bootstrapPlan.recipe,
         identity: bootstrapPlan.recipeIdentity,
-        defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+        // Harness infrastructure always lives under the sandbox's own HOME,
+        // never the working directory.
+        stateDirectory: harnessStateDirectoryPath({
+          sandboxHomeDir: await resolveSandboxHomeDir({
+            sandbox: restrictedSession,
+            abortSignal,
+          }),
+        }),
         abortSignal,
       });
     }

package/src/agent/prepare-sandbox-for-harness.ts

@@ -1,7 +1,9 @@
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { harnessStateDirectoryPath } from '../v1';
 import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
 import type { HarnessAgentAdapter } from './harness-agent-types';
 import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
+import { resolveSandboxHomeDir } from '../utils/sandbox-home-dir';
 import {
   applyBootstrapRecipe,
   hashHarnessBootstrap,
@@ -67,7 +69,7 @@ export async function prepareSandboxForHarness(options: {
       : normalizeSandboxWorkDir(sandboxConfig.workDir);
   const recipeIdentities: Record<string, string> = {};
   const skippedHarnessIds: string[] = [];
-  let defaultWorkingDirectory: string | undefined;
+  let stateDirectory: string | undefined;
 
   for (const harness of harnesses) {
     const recipe = await harness.getBootstrap?.({
@@ -80,20 +82,27 @@ export async function prepareSandboxForHarness(options: {
 
     const recipeIdentity = await hashHarnessBootstrap(recipe);
     recipeIdentities[harness.harnessId] = recipeIdentity;
-    defaultWorkingDirectory ??= await resolveSandboxDefaultWorkingDirectory({
-      sandboxSession: options.session,
-      abortSignal: options.abortSignal,
+    // Harness infrastructure always lives under the sandbox's own HOME,
+    // never the working directory.
+    stateDirectory ??= harnessStateDirectoryPath({
+      sandboxHomeDir: await resolveSandboxHomeDir({
+        sandbox: options.session,
+        abortSignal: options.abortSignal,
+      }),
     });
     await applyBootstrapRecipe({
       session: options.session,
       recipe,
       identity: recipeIdentity,
-      defaultWorkingDirectory,
+      stateDirectory,
       abortSignal: options.abortSignal,
     });
   }
 
   if (sandboxConfig.onBootstrap != null) {
+    const defaultWorkingDirectory = await resolveSandboxDefaultWorkingDirectory(
+      { sandboxSession: options.session, abortSignal: options.abortSignal },
+    );
     await runSandboxBootstrap({
       session: options.session,
       workDir,

package/src/bridge/index.ts

@@ -934,7 +934,6 @@ export async function runBridge<TStart extends { type: 'start' }>(
         const data = (await onStop?.()) ?? {};
         sendControl(ws, { type: 'bridge-stop', data });
         drainThenExit(ws, 1000, 'stop');
-        return;
       }
     }
   };

package/src/utils/sandbox-channel.ts

@@ -83,6 +83,11 @@ type Listener<TOut extends { type: string }, T extends EventTypeOf<TOut>> = (
   event: Extract<TOut, { type: T }>,
 ) => void;
 
+type BufferedEvent<TOut extends { type: string }> = {
+  message: TOut;
+  listeners?: ReadonlyArray<Listener<TOut, EventTypeOf<TOut>>>;
+};
+
 /*
  * The agent and utilities entrypoints bundle this module separately. A global
  * symbol lets the agent recognize metadata attached by the channel's bundle
@@ -172,11 +177,18 @@ async function awaitWebSocketConnection({
 /**
  * Host-side typed wrapper around the bridge WebSocket connection.
  *
- * Buffers inbound messages until a listener for their type is registered, so
- * callers that subscribe asynchronously do not miss early frames. Inbound
- * dispatch is serialised through a promise chain so a `close` event that
- * arrives on the same microtask as the final `finish` message does not fire
- * close handlers until the message has been dispatched.
+ * Buffers inbound messages in arrival order while listeners attach, so callers
+ * do not miss or reorder early frames. Listener registration drains the
+ * ordered prefix synchronously. Selective listeners are given through the
+ * current task (including its microtasks) to attach before unhandled event
+ * types are retained independently, so they cannot block subscribed event
+ * types indefinitely. A listener that claims an already-buffered event still
+ * receives it if it unsubscribes before that ordered drain completes. Use
+ * {@link SandboxChannel.beginListenerAttachment} to define an explicit
+ * attachment boundary that spans asynchronous work. Inbound dispatch is
+ * serialised through a promise chain so a `close` event that arrives on the
+ * same microtask as the final `finish` message does not fire close handlers
+ * until the message has been dispatched.
  *
  * Survives transient disconnects. The bridge keeps running and
  * accumulates events in an in-memory log keyed by a monotonic `seq`; on an
@@ -193,7 +205,12 @@ export class SandboxChannel<
     EventTypeOf<TOut>,
     Set<Listener<TOut, EventTypeOf<TOut>>>
   >();
-  private readonly buffered = new Map<EventTypeOf<TOut>, TOut[]>();
+  private readonly buffered: BufferedEvent<TOut>[] = [];
+  private readonly bufferedByType = new Map<EventTypeOf<TOut>, TOut[]>();
+  private bufferedOffset = 0;
+  private flushingBuffered = false;
+  private bufferedFlushScheduled = false;
+  private listenerAttachmentDepth = 0;
   private readonly onCloseHandlers = new Set<
     (code: number, reason: string) => void
   >();
@@ -309,19 +326,46 @@ export class SandboxChannel<
     }
     set.add(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
 
-    const buffered = this.buffered.get(type);
-    if (buffered) {
-      this.buffered.delete(type);
-      for (const event of buffered) {
-        listener(event as Extract<TOut, { type: T }>);
-      }
+    this.captureBufferedListeners(type);
+    if (this.listenerAttachmentDepth > 0) {
+      return () => {
+        set!.delete(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
+      };
     }
 
+    this.flushBufferedType(type);
+    this.flushBuffered();
+    this.scheduleSelectiveBufferedFlush();
+
     return () => {
       set!.delete(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
     };
   }
 
+  /**
+   * Hold buffered event delivery while a consumer attaches a related set of
+   * listeners, including across asynchronous boundaries. Call the returned
+   * function once registration is complete. Buffered events are then replayed
+   * in arrival order; event types that remain unhandled are retained
+   * independently so they do not block subscribed types.
+   */
+  beginListenerAttachment(): () => void {
+    this.listenerAttachmentDepth++;
+    let finished = false;
+    return () => {
+      if (finished) return;
+      finished = true;
+      this.listenerAttachmentDepth--;
+      if (this.listenerAttachmentDepth > 0) return;
+
+      for (const type of this.listeners.keys()) {
+        this.flushBufferedType(type);
+      }
+      this.flushBuffered();
+      this.scheduleSelectiveBufferedFlush();
+    };
+  }
+
   onClose(handler: (code: number, reason: string) => void): void {
     this.onCloseHandlers.add(handler);
   }
@@ -645,13 +689,18 @@ export class SandboxChannel<
     }
     const type = message.type as EventTypeOf<TOut>;
     const set = this.listeners.get(type);
-    if (!set || set.size === 0) {
-      let bucket = this.buffered.get(type);
-      if (!bucket) {
-        bucket = [];
-        this.buffered.set(type, bucket);
-      }
-      bucket.push(message);
+    if (
+      this.listenerAttachmentDepth > 0 ||
+      this.bufferedOffset < this.buffered.length ||
+      !set ||
+      set.size === 0
+    ) {
+      this.buffered.push({
+        message,
+        ...(set != null && set.size > 0 ? { listeners: Array.from(set) } : {}),
+      });
+      this.flushBuffered();
+      this.scheduleSelectiveBufferedFlush();
       return;
     }
     for (const listener of set) {
@@ -659,6 +708,110 @@ export class SandboxChannel<
     }
   }
 
+  private flushBuffered({
+    selective = false,
+  }: { selective?: boolean } = {}): void {
+    if (this.flushingBuffered || this.listenerAttachmentDepth > 0) return;
+    this.flushingBuffered = true;
+    try {
+      while (this.bufferedOffset < this.buffered.length) {
+        const bufferedEvent = this.buffered[this.bufferedOffset];
+        const message = bufferedEvent.message;
+        const type = message.type as EventTypeOf<TOut>;
+        const set = this.listeners.get(type);
+        const listeners =
+          bufferedEvent.listeners ??
+          (set != null && set.size > 0 ? Array.from(set) : undefined);
+        if (!listeners || listeners.length === 0) {
+          if (!selective) return;
+          this.bufferedOffset++;
+          const buffered = this.bufferedByType.get(type);
+          if (buffered) {
+            buffered.push(message);
+          } else {
+            this.bufferedByType.set(type, [message]);
+          }
+          continue;
+        }
+
+        this.bufferedOffset++;
+        for (const listener of listeners) {
+          listener(message as Extract<TOut, { type: EventTypeOf<TOut> }>);
+        }
+      }
+    } finally {
+      if (this.bufferedOffset > 0) {
+        this.buffered.splice(0, this.bufferedOffset);
+        this.bufferedOffset = 0;
+      }
+      this.flushingBuffered = false;
+    }
+  }
+
+  private captureBufferedListeners(type: EventTypeOf<TOut>): void {
+    const set = this.listeners.get(type);
+    if (!set || set.size === 0) return;
+
+    for (let i = this.bufferedOffset; i < this.buffered.length; i++) {
+      const bufferedEvent = this.buffered[i];
+      if (
+        bufferedEvent.listeners == null &&
+        bufferedEvent.message.type === type
+      ) {
+        bufferedEvent.listeners = Array.from(set);
+      }
+    }
+  }
+
+  private flushBufferedType(type: EventTypeOf<TOut>): void {
+    const buffered = this.bufferedByType.get(type);
+    if (!buffered) return;
+
+    let offset = 0;
+    try {
+      while (offset < buffered.length) {
+        const set = this.listeners.get(type);
+        if (!set || set.size === 0) return;
+
+        const message = buffered[offset++];
+        for (const listener of set) {
+          listener(message as Extract<TOut, { type: EventTypeOf<TOut> }>);
+        }
+      }
+    } finally {
+      if (offset === buffered.length) {
+        this.bufferedByType.delete(type);
+      } else if (offset > 0) {
+        buffered.splice(0, offset);
+      }
+    }
+  }
+
+  private scheduleSelectiveBufferedFlush(): void {
+    if (
+      this.bufferedFlushScheduled ||
+      this.bufferedOffset >= this.buffered.length ||
+      !this.hasListeners() ||
+      this.listenerAttachmentDepth > 0
+    ) {
+      return;
+    }
+
+    this.bufferedFlushScheduled = true;
+    setTimeout(() => {
+      this.bufferedFlushScheduled = false;
+      if (this.listenerAttachmentDepth > 0) return;
+      this.flushBuffered({ selective: true });
+    }, 0);
+  }
+
+  private hasListeners(): boolean {
+    for (const listeners of this.listeners.values()) {
+      if (listeners.size > 0) return true;
+    }
+    return false;
+  }
+
   private attachEventCheckpoint(options: {
     event: TOut;
     eventId: number;

package/src/utils/write-instructions.ts

@@ -207,7 +207,7 @@ function resolveInstructionsFilePath({
     );
   }
   const containsTraversal = instructionsFile
-    .split(/[\\\/]/)
+    .split(/[\\/]/)
     .some(segment => segment === '..');
   const normalizedInstructionsFile = path.posix.normalize(
     instructionsFile.trim(),

package/src/utils/write-skills.ts

@@ -551,7 +551,7 @@ function resolveSkillsRootDir({
     );
   }
   const containsTraversal = skillsDir
-    .split(/[\\\/]/)
+    .split(/[\\/]/)
     .some(segment => segment === '..');
   const normalizedSkillsDir = path.posix.normalize(skillsDir.trim());
   const normalizedNoTrailingSlash = normalizedSkillsDir.replace(/\/+$/, '');

package/src/v1/harness-session-data-directory-path.ts

@@ -0,0 +1,28 @@
+import { posix } from 'node:path';
+
+export function encodeHarnessPathSegment(value: string): string {
+  const encoded = encodeURIComponent(value);
+  if (encoded === '') return '%';
+  if (encoded === '.') return '%2E';
+  if (encoded === '..') return '%2E%2E';
+  return encoded;
+}
+
+/**
+ * Return the per-session harness state path under `.agent-runs`. Session IDs
+ * occupy one encoded path segment, so path separators and parent-directory
+ * references cannot move session data outside the harness state directory.
+ */
+export function harnessSessionDataDirectoryPath({
+  stateDirectory,
+  sessionId,
+}: {
+  stateDirectory: string;
+  sessionId: string;
+}): string {
+  return posix.join(
+    stateDirectory,
+    '.agent-runs',
+    encodeHarnessPathSegment(sessionId),
+  );
+}