@peakflo/agent-harness 0.2.16 → 0.2.17-rc.2

package/dist/github-workspace.d.ts

@@ -2,6 +2,8 @@ import { type RequestListener, type Server } from 'node:http';
 import type { WorkspaceProvider, WorkspaceRequest } from './ports';
 import type { PeerUidResolver } from './runtime/loopback-peer';
 import type { LeasedGitHubCredential } from './types';
+/** Compare repository identity without retaining URL credentials or a branch. */
+export declare function githubRepositoryIdentity(remote: string): string | null;
 export interface GitHubWorkspaceOptions {
     root: string;
     port?: number;
@@ -29,16 +31,20 @@ export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
     private caCertificatePath;
     private readonly restartNotedSessions;
     private readonly restoredWorktreeNotes;
+    private readonly preparationNotes;
     private readonly preparedWorktrees;
     private readonly directHosts;
     constructor(options: GitHubWorkspaceOptions);
     private rememberDirectUrls;
     private runGit;
+    private sameRepository;
+    /** Never fetch a different repository into a shared durable bare clone. */
+    private bareRepositoryPath;
+    private isUnusableCheckout;
     /**
-     * A harness crash must not erase or recreate a session checkout. Accept an
-     * existing path only when Git proves that it is the exact worktree this
-     * provider would have created: same canonical root, same bare repository,
-     * and same per-session branch. Anything else fails closed.
+     * A session owns its checkout, including branch changes and detached HEAD.
+     * Check its root and repository identity, never its branch or commit. Keep
+     * an unrelated or unusable checkout aside before preparing a replacement.
      */
     private canReuseWorktree;
     private dirtyFileCount;
@@ -56,6 +62,7 @@ export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
     prepare(request: WorkspaceRequest): Promise<string>;
     getEnvironment(sessionId: string, directUrls?: string[]): Record<string, string>;
     takeTurnNote(sessionId: string): string | null;
+    takePreparationNotes(sessionId: string): string[];
     preserveAtTurnEnd(sessionId: string): Promise<boolean>;
     release(sessionId: string, options?: {
         force?: boolean;

package/dist/github-workspace.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitHubWorkspaceProvider = void 0;
+exports.githubRepositoryIdentity = githubRepositoryIdentity;
 exports.directHostnames = directHostnames;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -18,6 +19,28 @@ const DEFAULT_PROXY_PORT = 7780;
 const LINK_SECRET_FILE = '.github-proxy-link-secret';
 const WIP_PUSH_FAILED_FILE = '.worktree-wip-push-failed';
 const WIP_COMMIT_MESSAGE = 'chore(agent): wip — uncommitted at turn end';
+/** Compare repository identity without retaining URL credentials or a branch. */
+function githubRepositoryIdentity(remote) {
+    const ssh = /^git@github\.com:(.+)$/i.exec(remote);
+    try {
+        const url = new URL(ssh ? `https://github.com/${ssh[1]}` : remote);
+        const host = url.hostname.toLowerCase();
+        // Within a harness-owned checkout/cache, loopback owner/repo URLs denote
+        // the GitHub proxy. This is not proof of identity for arbitrary local URLs.
+        if (!['github.com', '127.0.0.1', 'localhost', '[::1]'].includes(host)) {
+            return null;
+        }
+        if (!['https:', 'http:', 'ssh:'].includes(url.protocol))
+            return null;
+        const path = url.pathname.replace(/\/$/, '').replace(/\.git$/i, '');
+        if (!/^\/[a-z0-9_.-]+\/[a-z0-9_.-]+$/i.test(path))
+            return null;
+        return `github.com${path.toLowerCase()}`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Hostnames of URLs the agent reaches WITHOUT a proxy (control plane, model
  * gateway, MCP). Shared with the credential proxy's NO_PROXY so both proxies
@@ -49,6 +72,7 @@ class GitHubWorkspaceProvider {
     caCertificatePath = null;
     restartNotedSessions = new Set();
     restoredWorktreeNotes = new Map();
+    preparationNotes = new Map();
     preparedWorktrees = new Map();
     directHosts = new Set();
     constructor(options) {
@@ -76,13 +100,64 @@ class GitHubWorkspaceProvider {
             env: { ...this.gitEnvironment, ...environment }
         });
     }
+    async sameRepository(expectedUrl, actualUrl, cwd) {
+        const expected = githubRepositoryIdentity(expectedUrl);
+        if (expected)
+            return githubRepositoryIdentity(actualUrl) === expected;
+        try {
+            return ((await (0, promises_1.realpath)((0, node_path_1.resolve)(cwd, actualUrl))) ===
+                (await (0, promises_1.realpath)(expectedUrl)));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Never fetch a different repository into a shared durable bare clone. */
+    async bareRepositoryPath(path, cloneUrl) {
+        const identity = githubRepositoryIdentity(cloneUrl) ?? cloneUrl;
+        const digest = (0, node_crypto_1.createHash)('sha256')
+            .update(identity)
+            .digest('hex')
+            .slice(0, 16);
+        // Leave old clones and linked worktrees intact. Bound collision handling
+        // without appending the same suffix recursively to a file name.
+        for (let attempt = 0; attempt < 16; attempt += 1) {
+            const candidate = attempt === 0 ? path : `${path}.recovered-${digest}-${attempt}`;
+            try {
+                const entry = await (0, promises_1.lstat)(candidate);
+                if (!entry.isDirectory() || entry.isSymbolicLink())
+                    continue;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return candidate;
+                throw error;
+            }
+            const origin = await this.runGit(['config', '--get', 'remote.origin.url'], {
+                cwd: candidate
+            }).catch((error) => {
+                if (this.isUnusableCheckout(error) || error.code === 1)
+                    return null;
+                throw new Error('Could not inspect repository cache. Existing files were kept.');
+            });
+            if (origin &&
+                (await this.sameRepository(cloneUrl, origin.stdout.trim(), candidate))) {
+                return candidate;
+            }
+        }
+        throw new Error('Could not prepare a repository cache. Existing files were kept.');
+    }
+    isUnusableCheckout(error) {
+        const gitError = error;
+        return (gitError.code === 128 &&
+            /not a git repository|invalid gitfile format|bad config line/i.test(gitError.stderr ?? ''));
+    }
     /**
-     * A harness crash must not erase or recreate a session checkout. Accept an
-     * existing path only when Git proves that it is the exact worktree this
-     * provider would have created: same canonical root, same bare repository,
-     * and same per-session branch. Anything else fails closed.
+     * A session owns its checkout, including branch changes and detached HEAD.
+     * Check its root and repository identity, never its branch or commit. Keep
+     * an unrelated or unusable checkout aside before preparing a replacement.
      */
-    async canReuseWorktree(bare, worktree, branch) {
+    async canReuseWorktree(bare, worktree, cloneUrl, sessionId) {
         let entry;
         try {
             entry = await (0, promises_1.lstat)(worktree);
@@ -92,33 +167,66 @@ class GitHubWorkspaceProvider {
                 return false;
             throw error;
         }
-        if (!entry.isDirectory() || entry.isSymbolicLink()) {
-            throw new Error(`Existing repository workspace is not a directory: ${worktree}`);
-        }
-        try {
-            const [topLevel, commonDir, currentBranch] = await Promise.all([
-                this.runGit(['rev-parse', '--show-toplevel'], { cwd: worktree }),
-                this.runGit(['rev-parse', '--git-common-dir'], { cwd: worktree }),
-                this.runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], {
-                    cwd: worktree
-                })
-            ]);
-            const [expectedWorktree, actualWorktree, expectedBare, actualBare] = await Promise.all([
-                (0, promises_1.realpath)(worktree),
-                (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, topLevel.stdout.trim())),
-                (0, promises_1.realpath)(bare),
-                (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, commonDir.stdout.trim()))
-            ]);
-            if (actualWorktree !== expectedWorktree ||
-                actualBare !== expectedBare ||
-                currentBranch.stdout.trim() !== branch) {
-                throw new Error('repository or branch does not match');
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            try {
+                const [topLevel, origin, commonDir] = await Promise.all([
+                    this.runGit(['rev-parse', '--show-toplevel'], { cwd: worktree }),
+                    this.runGit(['config', '--get', 'remote.origin.url'], {
+                        cwd: worktree
+                    }).catch((error) => {
+                        if (error.code === 1 && !error.stderr)
+                            return { stdout: '' };
+                        throw error;
+                    }),
+                    this.runGit(['rev-parse', '--git-common-dir'], { cwd: worktree })
+                ]);
+                const [expectedWorktree, actualWorktree, repositoriesRoot, actualCommon] = await Promise.all([
+                    (0, promises_1.realpath)(worktree),
+                    (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, topLevel.stdout.trim())),
+                    (0, promises_1.realpath)((0, node_path_1.join)((0, node_path_1.resolve)(this.options.root), '.repositories')),
+                    (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, commonDir.stdout.trim()))
+                ]);
+                const sameRepository = await this.sameRepository(cloneUrl, origin.stdout.trim(), worktree);
+                const managedCommon = actualCommon.startsWith(`${repositoriesRoot}/`) ||
+                    actualCommon === (0, node_path_1.join)(expectedWorktree, '.git');
+                if (actualWorktree === expectedWorktree &&
+                    sameRepository &&
+                    managedCommon)
+                    return true;
+            }
+            catch (error) {
+                // Only a proven broken Git checkout is moved. Resource exhaustion,
+                // permission errors and timeouts must leave a healthy checkout in place.
+                // Do not echo Git errors: they can contain remote credentials.
+                if (!this.isUnusableCheckout(error)) {
+                    throw new Error('Could not inspect the existing repository workspace. Retry the message. Existing files were not changed.');
+                }
             }
-            return true;
         }
-        catch (error) {
-            throw new Error(`Existing repository workspace cannot be reused safely: ${worktree}: ${error instanceof Error ? error.message : String(error)}`);
+        const backupRoot = await (0, promises_1.mkdtemp)((0, node_path_1.join)(this.sessionPath(sessionId), `.preserved-${Date.now()}-`));
+        const backup = (0, node_path_1.join)(backupRoot, 'repository');
+        // Git updates a linked worktree's administrative paths when possible.
+        // A plain directory, symlink or broken checkout still keeps all bytes.
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            await this.runGit(['worktree', 'move', worktree, backup], {
+                cwd: worktree
+            }).catch(async () => {
+                await (0, promises_1.rename)(worktree, backup);
+                await this.runGit(['worktree', 'repair', backup], { cwd: bare }).catch(() => undefined);
+            });
         }
+        else {
+            await (0, promises_1.rename)(worktree, backup);
+        }
+        // A broken .git file cannot be repaired. Remove only obsolete Git
+        // registrations now, before reusing the vacated path; keep all saved files.
+        await this.runGit(['worktree', 'prune', '--expire=now'], { cwd: bare });
+        const notes = this.preparationNotes.get(sessionId) ?? [];
+        notes.push(`The previous repository folder could not be reused. All its files ` +
+            `were kept at ${backup}. A fresh checkout was prepared. ` +
+            'Review the saved folder before you remove it.');
+        this.preparationNotes.set(sessionId, notes);
+        return false;
     }
     async dirtyFileCount(worktree) {
         const status = await this.runGit(['status', '--porcelain=v1', '-z'], {
@@ -331,7 +439,7 @@ class GitHubWorkspaceProvider {
         let reusedWorktree = false;
         for (const repository of request.repositories) {
             const [owner, name] = repository.fullName.split('/');
-            const bare = (0, node_path_1.join)(repositoriesRoot, `${owner}--${name}.git`);
+            const bare = await this.bareRepositoryPath((0, node_path_1.join)(repositoriesRoot, `${owner}--${name}.git`), repository.cloneUrl);
             const worktree = (0, node_path_1.join)(sessionRoot, name);
             // The empty value resets every inherited/global helper. Without it, Git
             // can pass the installation token to a desktop keychain helper on the
@@ -359,6 +467,11 @@ class GitHubWorkspaceProvider {
                     '+refs/heads/*:refs/remotes/origin/*'
                 ], { cwd: bare });
             }
+            // The identity check above permits old proxy/sentinel URL forms. Fetch
+            // through the current lease URL so a stale loopback port cannot fail first.
+            await this.runGit(['config', 'remote.origin.url', repository.cloneUrl], {
+                cwd: bare
+            });
             await this.runGit([...gitArgs, 'fetch', 'origin', '+refs/heads/*:refs/remotes/origin/*'], {
                 cwd: bare,
                 timeout: 10 * 60_000,
@@ -367,7 +480,7 @@ class GitHubWorkspaceProvider {
             });
             await this.runGit(['worktree', 'prune'], { cwd: bare });
             const branch = `agent/${request.sessionId}`;
-            const reuse = await this.canReuseWorktree(bare, worktree, branch);
+            const reuse = await this.canReuseWorktree(bare, worktree, repository.cloneUrl, request.sessionId);
             if (!reuse) {
                 try {
                     await this.runGit(['worktree', 'add', worktree, branch], {
@@ -375,14 +488,17 @@ class GitHubWorkspaceProvider {
                     });
                 }
                 catch {
-                    await this.runGit([
-                        'worktree',
-                        'add',
-                        '-b',
-                        branch,
-                        worktree,
-                        `origin/${repository.defaultBranch}`
-                    ], { cwd: bare });
+                    const existingBranch = await this.runGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: bare }).then(() => true, () => false);
+                    await this.runGit(existingBranch
+                        ? ['worktree', 'add', '--detach', worktree, branch]
+                        : [
+                            'worktree',
+                            'add',
+                            '-b',
+                            branch,
+                            worktree,
+                            `origin/${repository.defaultBranch}`
+                        ], { cwd: bare });
                 }
             }
             else {
@@ -400,12 +516,15 @@ class GitHubWorkspaceProvider {
             });
             // Hooks must be per worktree; a shared bare-repo hook would overwrite
             // another session's allowed destination when sessions overlap.
+            // A reused checkout may belong to a recovered cache or a standalone clone.
+            // Configure its actual common directory, rather than the default cache.
             await this.runGit(['config', 'extensions.worktreeConfig', 'true'], {
-                cwd: bare
+                cwd: worktree
             });
             await this.runGit(['config', '--worktree', 'core.bare', 'false'], {
                 cwd: worktree
             });
+            await this.runGit(['config', '--worktree', 'remote.origin.url', repository.cloneUrl], { cwd: worktree });
             const hooks = (0, node_path_1.join)(sessionRoot, '.github-hooks', name);
             await (0, github_command_guards_1.installPushGuard)(hooks, request.sessionId, repository.defaultBranch, repository.cloneUrl);
             await this.runGit(['config', '--worktree', 'core.hooksPath', hooks], {
@@ -504,6 +623,11 @@ class GitHubWorkspaceProvider {
             .filter(Boolean)
             .join('\n');
     }
+    takePreparationNotes(sessionId) {
+        const notes = this.preparationNotes.get(sessionId) ?? [];
+        this.preparationNotes.delete(sessionId);
+        return notes;
+    }
     async preserveAtTurnEnd(sessionId) {
         const worktrees = await this.worktreesForSession(sessionId);
         const failures = await this.readFailedPushes(sessionId);
@@ -563,6 +687,7 @@ class GitHubWorkspaceProvider {
         await (0, promises_1.rm)(this.sessionPath(sessionId), { recursive: true, force: true });
         this.preparedWorktrees.delete(sessionId);
         this.restoredWorktreeNotes.delete(sessionId);
+        this.preparationNotes.delete(sessionId);
         this.restartNotedSessions.delete(sessionId);
         this.clearCredential(sessionId);
         return true;

package/dist/ports.d.ts

@@ -389,6 +389,8 @@ export interface WorkspaceProvider {
     getEnvironment?(sessionId: string, directUrls?: string[]): Record<string, string>;
     /** One-use host note to prepend to the next model turn, when present. */
     takeTurnNote?(sessionId: string): string | null;
+    /** Recovery notices to show in the transcript and pass to the model. */
+    takePreparationNotes?(sessionId: string): string[];
     /**
      * Save dirty repository work before a turn gives up its credential.
      * A false result means a remote backup failed and cleanup must keep the tree.

package/dist/runtime/session-runner.js

@@ -859,6 +859,20 @@ class SessionRunner {
                         .join('\n')
                     : `Repository workspace was not prepared: ${reason}`);
             }
+            const workspaceNotes = this.deps.workspace.takePreparationNotes?.(session.sessionId) ?? [];
+            if (workspaceNotes.length > 0) {
+                const content = workspaceNotes.join('\n');
+                turnContent = `${content}\n\n${turnContent}`;
+                partsProduced += this.record(session.sessionId, [
+                    {
+                        id: `workspace-recovery-${session.turnId}`,
+                        role: 'system',
+                        partType: 'text',
+                        content
+                    }
+                ]);
+                await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+            }
             /*
              * THE USER'S ATTACHMENTS, INTO THIS TURN'S WORKSPACE — every turn, since
              * each lease carries its own turn's files and the session may have moved

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.16",
+  "version": "0.2.17-rc.2",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",