@peakflo/agent-harness 0.2.26-rc.1 → 0.2.27-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,6 +13,11 @@ export interface GitHubWorkspaceOptions {
13
13
  allowDirectHttps?: boolean;
14
14
  /** Injected in tests: the proxy's peer-uid lookup. See `GitHubTlsProxy`. */
15
15
  peerUid?: PeerUidResolver;
16
+ /**
17
+ * Whether the workspace file system ignores case. Detected with a probe file
18
+ * when unset. Injected in tests.
19
+ */
20
+ caseInsensitiveFilesystem?: boolean;
16
21
  }
17
22
  /**
18
23
  * Hostnames of URLs the agent reaches WITHOUT a proxy (control plane, model
@@ -20,7 +25,6 @@ export interface GitHubWorkspaceOptions {
20
25
  * bypass exactly the same hosts.
21
26
  */
22
27
  export declare function directHostnames(urls: string[]): string[];
23
- /** Bare clone plus one worktree per session, adapted from 20x. */
24
28
  export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
25
29
  private readonly options;
26
30
  private readonly sessions;
@@ -65,6 +69,58 @@ export declare class GitHubWorkspaceProvider implements WorkspaceProvider {
65
69
  private sessionPath;
66
70
  private ensureServer;
67
71
  private startServer;
72
+ private readonly repositoryLocks;
73
+ /** Run `task` after every earlier task for the same cache has finished. */
74
+ private withRepositoryLock;
75
+ private addNote;
76
+ private isUsableBareRepository;
77
+ private fetchCache;
78
+ /** Linked checkouts of this cache that still exist on disk. */
79
+ private liveWorktreeCount;
80
+ /**
81
+ * Replace the cache with a fresh clone. The clone goes to a new folder, is
82
+ * checked, and then moved into place with one rename. The old folder is kept
83
+ * under a new name, never deleted. A cache that live checkouts point at is
84
+ * not swapped: that would break their Git link.
85
+ */
86
+ private replaceCache;
87
+ /** The newest usable `origin/<branch>`, or null when none resolves. */
88
+ private resolveBaseRef;
89
+ /** Can the base commit's files be read? A missing object shows here. */
90
+ private canReadBase;
91
+ /**
92
+ * Make the cache usable and return the base ref for a new checkout. A cache
93
+ * that is missing, empty, damaged or without the default branch is replaced
94
+ * once with a fresh clone. An access or network failure is reported as such:
95
+ * a fresh clone would fail the same way.
96
+ */
97
+ private prepareCache;
98
+ /**
99
+ * Make the cache's own settings right: the fetch refspec, and a HEAD that
100
+ * points at a real branch. A clone that stopped early leaves HEAD at the
101
+ * placeholder `refs/heads/.invalid`, and `git worktree add` needs a valid HEAD
102
+ * ("failed to resolve HEAD as a valid ref"). Repair it from the default
103
+ * branch the harness just found.
104
+ */
105
+ private repairCache;
106
+ private hasMarker;
107
+ /** Written only after a clone or an old cache has passed every check. */
108
+ private markComplete;
109
+ private refFormatOf;
110
+ private caseInsensitive;
111
+ /** Probe the workspace file system once: do `a` and `A` name one file? */
112
+ private isCaseInsensitiveFilesystem;
113
+ private gitVersion;
114
+ private getGitVersion;
115
+ /**
116
+ * Move a `files` cache to `reftable` on a file system that ignores case, so
117
+ * branches that differ only in case can be stored. A copy is made first and
118
+ * kept. A cache with live checkouts is left alone: Git cannot migrate it.
119
+ * Returns true when the cache was migrated.
120
+ */
121
+ private migrateRefs;
122
+ /** Add the session checkout. A damaged cache is replaced once, then retried. */
123
+ private addWorktree;
68
124
  prepare(request: WorkspaceRequest): Promise<string>;
69
125
  getEnvironment(sessionId: string, directUrls?: string[]): Record<string, string>;
70
126
  takeTurnNote(sessionId: string): string | null;
@@ -13,6 +13,7 @@ const node_util_1 = require("node:util");
13
13
  const vendor_environment_1 = require("./adapters/vendor-environment");
14
14
  const github_proxy_1 = require("./github-proxy");
15
15
  const github_proxy_certificates_1 = require("./github-proxy-certificates");
16
+ const repository_cache_1 = require("./repository-cache");
16
17
  const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
17
18
  const DEFAULT_PROXY_PORT = 7780;
18
19
  const LINK_SECRET_FILE = '.github-proxy-link-secret';
@@ -59,7 +60,6 @@ function directHostnames(urls) {
59
60
  }
60
61
  return hosts;
61
62
  }
62
- /** Bare clone plus one worktree per session, adapted from 20x. */
63
63
  class GitHubWorkspaceProvider {
64
64
  options;
65
65
  sessions = new Map();
@@ -484,6 +484,391 @@ class GitHubWorkspaceProvider {
484
484
  this.port = address.port;
485
485
  return this.port;
486
486
  }
487
+ /* ---------------------------------------------------------------- */
488
+ /* Repository cache */
489
+ /* ---------------------------------------------------------------- */
490
+ repositoryLocks = new Map();
491
+ /** Run `task` after every earlier task for the same cache has finished. */
492
+ async withRepositoryLock(key, task) {
493
+ const previous = this.repositoryLocks.get(key) ?? Promise.resolve();
494
+ const run = previous.then(task);
495
+ const tail = run.then(() => undefined, () => undefined);
496
+ this.repositoryLocks.set(key, tail);
497
+ try {
498
+ return await run;
499
+ }
500
+ finally {
501
+ if (this.repositoryLocks.get(key) === tail)
502
+ this.repositoryLocks.delete(key);
503
+ }
504
+ }
505
+ addNote(sessionId, note) {
506
+ const notes = this.preparationNotes.get(sessionId) ?? [];
507
+ notes.push(note);
508
+ this.preparationNotes.set(sessionId, notes);
509
+ (this.options.logger ?? console).warn(`[GitHubWorkspace] ${note}`);
510
+ }
511
+ async isUsableBareRepository(bare) {
512
+ try {
513
+ await this.runGit(['rev-parse', '--is-bare-repository'], { cwd: bare });
514
+ return true;
515
+ }
516
+ catch {
517
+ return false;
518
+ }
519
+ }
520
+ fetchCache(cache) {
521
+ // Fetch through the current lease URL so a stale loopback port cannot fail
522
+ // first. The explicit refspec does not depend on the saved configuration.
523
+ return this.runGit([
524
+ ...cache.gitArgs,
525
+ 'fetch',
526
+ cache.transportUrl,
527
+ '+refs/heads/*:refs/remotes/origin/*'
528
+ ], {
529
+ cwd: cache.bare,
530
+ timeout: 10 * 60_000,
531
+ maxBuffer: 10 * 1024 * 1024,
532
+ environment: cache.environment
533
+ });
534
+ }
535
+ /** Linked checkouts of this cache that still exist on disk. */
536
+ async liveWorktreeCount(bare) {
537
+ let entries;
538
+ try {
539
+ entries = await (0, promises_1.readdir)((0, node_path_1.join)(bare, 'worktrees'));
540
+ }
541
+ catch {
542
+ return 0;
543
+ }
544
+ let live = 0;
545
+ for (const entry of entries) {
546
+ try {
547
+ const gitdir = (await (0, promises_1.readFile)((0, node_path_1.join)(bare, 'worktrees', entry, 'gitdir'), 'utf8')).trim();
548
+ await (0, promises_1.lstat)((0, node_path_1.dirname)(gitdir));
549
+ live += 1;
550
+ }
551
+ catch {
552
+ /* a registration without a checkout is not in use */
553
+ }
554
+ }
555
+ return live;
556
+ }
557
+ /**
558
+ * Replace the cache with a fresh clone. The clone goes to a new folder, is
559
+ * checked, and then moved into place with one rename. The old folder is kept
560
+ * under a new name, never deleted. A cache that live checkouts point at is
561
+ * not swapped: that would break their Git link.
562
+ */
563
+ async replaceCache(cache, sessionId) {
564
+ const existing = await (0, promises_1.lstat)(cache.bare).then(() => true, () => false);
565
+ if (existing && (await this.liveWorktreeCount(cache.bare)) > 0) {
566
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, 'in-use', (0, repository_cache_1.describeFailure)(cache.fullName, 'in-use'));
567
+ }
568
+ const fresh = `${cache.bare}.new-${process.pid}-${(0, node_crypto_1.randomBytes)(4).toString('hex')}`;
569
+ try {
570
+ const reftable = (0, repository_cache_1.shouldUseReftable)({
571
+ caseInsensitive: await this.isCaseInsensitiveFilesystem(),
572
+ git: await this.getGitVersion()
573
+ });
574
+ if (!reftable && (await this.isCaseInsensitiveFilesystem())) {
575
+ this.addNote(sessionId, `Repository ${cache.fullName}: this computer ignores upper and lower case in file names and Git is older than 2.45. Branches that differ only in case may be skipped. Update Git to fix this.`);
576
+ }
577
+ await this.runGit([
578
+ ...cache.gitArgs,
579
+ 'clone',
580
+ '--bare',
581
+ ...(reftable ? ['--ref-format=reftable'] : []),
582
+ cache.transportUrl,
583
+ fresh
584
+ ], {
585
+ timeout: 10 * 60_000,
586
+ maxBuffer: 10 * 1024 * 1024,
587
+ environment: cache.environment
588
+ });
589
+ await this.runGit([
590
+ 'config',
591
+ '--replace-all',
592
+ 'remote.origin.fetch',
593
+ '+refs/heads/*:refs/remotes/origin/*'
594
+ ], { cwd: fresh });
595
+ // A clone of an empty repository succeeds with no branch at all.
596
+ const branches = await this.runGit(['for-each-ref', '--count=1', 'refs/heads'], { cwd: fresh });
597
+ if (!branches.stdout.trim()) {
598
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, 'no-default-branch', (0, repository_cache_1.describeFailure)(cache.fullName, 'no-default-branch'));
599
+ }
600
+ if (existing) {
601
+ const aside = `${cache.bare}.broken-${Date.now()}`;
602
+ await (0, promises_1.rename)(cache.bare, aside);
603
+ this.addNote(sessionId, `Repository ${cache.fullName}: the saved local copy was damaged. It was moved to ${aside} and a fresh clone was made.`);
604
+ }
605
+ await (0, promises_1.rename)(fresh, cache.bare);
606
+ }
607
+ catch (error) {
608
+ await (0, promises_1.rm)(fresh, { recursive: true, force: true }).catch(() => undefined);
609
+ throw error;
610
+ }
611
+ }
612
+ /** The newest usable `origin/<branch>`, or null when none resolves. */
613
+ async resolveBaseRef(cache, preferred) {
614
+ const text = async (args) => (await this.runGit(args, { cwd: cache.bare })).stdout.trim();
615
+ const exists = (branch) => this.runGit([
616
+ 'rev-parse',
617
+ '--verify',
618
+ '--quiet',
619
+ `refs/remotes/origin/${branch}^{commit}`
620
+ ], { cwd: cache.bare }).then(() => true, () => false);
621
+ const headBranch = await text(['symbolic-ref', '-q', 'HEAD']).then((ref) => ref.replace(/^refs\/heads\//, '') || null, () => null);
622
+ const originHeadBranch = await text([
623
+ 'symbolic-ref',
624
+ '-q',
625
+ 'refs/remotes/origin/HEAD'
626
+ ]).then((ref) => ref.replace(/^refs\/remotes\/origin\//, '') || null, () => null);
627
+ const tried = new Set();
628
+ for (const branch of (0, repository_cache_1.baseBranchCandidates)({
629
+ preferred,
630
+ headBranch,
631
+ originHeadBranch
632
+ })) {
633
+ tried.add(branch);
634
+ if (await exists(branch))
635
+ return `origin/${branch}`;
636
+ }
637
+ // Last, ask GitHub which branch is the default now.
638
+ const remote = await this.runGit([...cache.gitArgs, 'ls-remote', '--symref', cache.transportUrl, 'HEAD'], { cwd: cache.bare, timeout: 60_000, environment: cache.environment }).then((result) => (0, repository_cache_1.parseRemoteDefaultBranch)(result.stdout), () => null);
639
+ if (remote && !tried.has(remote) && (await exists(remote)))
640
+ return `origin/${remote}`;
641
+ return null;
642
+ }
643
+ /** Can the base commit's files be read? A missing object shows here. */
644
+ canReadBase(cache, base) {
645
+ return this.runGit(['ls-tree', '--name-only', base], {
646
+ cwd: cache.bare,
647
+ maxBuffer: 10 * 1024 * 1024
648
+ }).then(() => true, () => false);
649
+ }
650
+ /**
651
+ * Make the cache usable and return the base ref for a new checkout. A cache
652
+ * that is missing, empty, damaged or without the default branch is replaced
653
+ * once with a fresh clone. An access or network failure is reported as such:
654
+ * a fresh clone would fail the same way.
655
+ */
656
+ async prepareCache(cache, defaultBranch, sessionId) {
657
+ let replaced = false;
658
+ const replace = async () => {
659
+ if (replaced) {
660
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, 'damaged', (0, repository_cache_1.describeFailure)(cache.fullName, 'damaged'));
661
+ }
662
+ replaced = true;
663
+ await this.replaceCache(cache, sessionId);
664
+ };
665
+ const wrap = (error) => {
666
+ if (error instanceof repository_cache_1.RepositoryPrepareError)
667
+ throw error;
668
+ const kind = (0, repository_cache_1.classifyGitFailure)(error);
669
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, kind, (0, repository_cache_1.describeFailure)(cache.fullName, kind));
670
+ };
671
+ try {
672
+ if (!(await this.isUsableBareRepository(cache.bare)))
673
+ await replace();
674
+ }
675
+ catch (error) {
676
+ return wrap(error);
677
+ }
678
+ let migrated = false;
679
+ for (;;) {
680
+ try {
681
+ await this.fetchCache(cache);
682
+ }
683
+ catch (error) {
684
+ const kind = (0, repository_cache_1.classifyGitFailure)(error);
685
+ // No access or no network: a fresh clone fails the same way.
686
+ if (kind === 'auth' || kind === 'network')
687
+ return wrap(error);
688
+ // Anything else (a ref that cannot be stored, a lock on one ref) may
689
+ // touch refs the checkout does not need. Judge by the base ref below.
690
+ (this.options.logger ?? console).warn(`[GitHubWorkspace] ${cache.fullName}: the fetch did not finish for every branch. Continuing if the default branch is readable.`);
691
+ }
692
+ const base = await this.resolveBaseRef(cache, defaultBranch);
693
+ if (base && (await this.canReadBase(cache, base))) {
694
+ if (defaultBranch && base !== `origin/${defaultBranch}`) {
695
+ this.addNote(sessionId, `Repository ${cache.fullName}: the default branch is ${base.slice('origin/'.length)}, not ${defaultBranch}. The checkout starts from ${base}.`);
696
+ }
697
+ try {
698
+ await this.repairCache(cache, base);
699
+ if (!migrated && (await this.migrateRefs(cache, sessionId))) {
700
+ migrated = true;
701
+ // Branches that differ only in case can be stored now. Fetch once
702
+ // more for them; the checkout does not wait on the result.
703
+ await this.fetchCache(cache).catch(() => undefined);
704
+ }
705
+ await this.markComplete(cache);
706
+ }
707
+ catch (error) {
708
+ return wrap(error);
709
+ }
710
+ return base;
711
+ }
712
+ if (replaced) {
713
+ return wrap(new repository_cache_1.RepositoryPrepareError(cache.fullName, base ? 'damaged' : 'no-default-branch', (0, repository_cache_1.describeFailure)(cache.fullName, base ? 'damaged' : 'no-default-branch')));
714
+ }
715
+ this.addNote(sessionId, `Repository ${cache.fullName}: the local copy has no readable ${defaultBranch ?? 'default'} branch. Retrying with a fresh clone.`);
716
+ try {
717
+ await replace();
718
+ }
719
+ catch (error) {
720
+ return wrap(error);
721
+ }
722
+ }
723
+ }
724
+ /**
725
+ * Make the cache's own settings right: the fetch refspec, and a HEAD that
726
+ * points at a real branch. A clone that stopped early leaves HEAD at the
727
+ * placeholder `refs/heads/.invalid`, and `git worktree add` needs a valid HEAD
728
+ * ("failed to resolve HEAD as a valid ref"). Repair it from the default
729
+ * branch the harness just found.
730
+ */
731
+ async repairCache(cache, base) {
732
+ await this.runGit([
733
+ 'config',
734
+ '--replace-all',
735
+ 'remote.origin.fetch',
736
+ '+refs/heads/*:refs/remotes/origin/*'
737
+ ], { cwd: cache.bare });
738
+ const headValid = await this.runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { cwd: cache.bare }).then(() => true, () => false);
739
+ if (headValid)
740
+ return;
741
+ const branch = base.slice('origin/'.length);
742
+ const hasLocal = await this.runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}^{commit}`], { cwd: cache.bare }).then(() => true, () => false);
743
+ if (!hasLocal) {
744
+ await this.runGit(['update-ref', `refs/heads/${branch}`, `refs/remotes/${base}`], { cwd: cache.bare });
745
+ }
746
+ await this.runGit(['symbolic-ref', 'HEAD', `refs/heads/${branch}`], {
747
+ cwd: cache.bare
748
+ });
749
+ (this.options.logger ?? console).warn(`[GitHubWorkspace] ${cache.fullName}: HEAD of the local copy was invalid. It now points at ${branch}.`);
750
+ }
751
+ async hasMarker(bare) {
752
+ return (0, promises_1.lstat)((0, node_path_1.join)(bare, repository_cache_1.CLONE_MARKER)).then(() => true, () => false);
753
+ }
754
+ /** Written only after a clone or an old cache has passed every check. */
755
+ async markComplete(cache) {
756
+ if (await this.hasMarker(cache.bare))
757
+ return;
758
+ const refFormat = await this.refFormatOf(cache.bare);
759
+ await (0, promises_1.writeFile)((0, node_path_1.join)(cache.bare, repository_cache_1.CLONE_MARKER), JSON.stringify({ completedAt: new Date().toISOString(), refFormat }), { mode: 0o600 });
760
+ }
761
+ async refFormatOf(bare) {
762
+ return this.runGit(['rev-parse', '--show-ref-format'], { cwd: bare }).then((result) => result.stdout.trim() || 'files', () => 'files');
763
+ }
764
+ caseInsensitive = null;
765
+ /** Probe the workspace file system once: do `a` and `A` name one file? */
766
+ isCaseInsensitiveFilesystem() {
767
+ if (typeof this.options.caseInsensitiveFilesystem === 'boolean')
768
+ return Promise.resolve(this.options.caseInsensitiveFilesystem);
769
+ this.caseInsensitive ??= (async () => {
770
+ const dir = (0, node_path_1.join)((0, node_path_1.resolve)(this.options.root), '.repositories');
771
+ const name = `.pf-case-probe-${(0, node_crypto_1.randomBytes)(4).toString('hex')}`;
772
+ try {
773
+ await (0, promises_1.mkdir)(dir, { recursive: true, mode: 0o700 });
774
+ await (0, promises_1.writeFile)((0, node_path_1.join)(dir, name), '');
775
+ return await (0, promises_1.lstat)((0, node_path_1.join)(dir, name.toUpperCase())).then(() => true, () => false);
776
+ }
777
+ catch {
778
+ return false;
779
+ }
780
+ finally {
781
+ await (0, promises_1.unlink)((0, node_path_1.join)(dir, name)).catch(() => undefined);
782
+ }
783
+ })();
784
+ return this.caseInsensitive;
785
+ }
786
+ gitVersion = null;
787
+ getGitVersion() {
788
+ this.gitVersion ??= this.runGit(['--version']).then((result) => (0, repository_cache_1.parseGitVersion)(result.stdout), () => null);
789
+ return this.gitVersion;
790
+ }
791
+ /**
792
+ * Move a `files` cache to `reftable` on a file system that ignores case, so
793
+ * branches that differ only in case can be stored. A copy is made first and
794
+ * kept. A cache with live checkouts is left alone: Git cannot migrate it.
795
+ * Returns true when the cache was migrated.
796
+ */
797
+ async migrateRefs(cache, sessionId) {
798
+ const insensitive = await this.isCaseInsensitiveFilesystem();
799
+ if (!insensitive)
800
+ return false;
801
+ const refFormat = await this.refFormatOf(cache.bare);
802
+ if (!(0, repository_cache_1.shouldMigrateToReftable)({
803
+ caseInsensitive: insensitive,
804
+ git: await this.getGitVersion(),
805
+ refFormat,
806
+ liveWorktrees: await this.liveWorktreeCount(cache.bare)
807
+ }))
808
+ return false;
809
+ const backup = `${cache.bare}.backup-${Date.now()}`;
810
+ try {
811
+ // `-c` makes a copy-on-write clone on APFS. Fall back to a plain copy.
812
+ await execFileAsync('cp', ['-cR', cache.bare, backup]).catch(() => execFileAsync('cp', ['-R', cache.bare, backup]));
813
+ await this.runGit(['refs', 'migrate', '--ref-format=reftable'], {
814
+ cwd: cache.bare
815
+ });
816
+ if ((await this.refFormatOf(cache.bare)) !== 'reftable')
817
+ throw new Error('The ref format did not change.');
818
+ this.addNote(sessionId, `Repository ${cache.fullName}: this computer ignores upper and lower case in file names, so the local copy now stores branches in the reftable format. A copy of the old one is at ${backup}.`);
819
+ return true;
820
+ }
821
+ catch {
822
+ (this.options.logger ?? console).warn(`[GitHubWorkspace] ${cache.fullName}: the ref format could not be changed. The local copy is unchanged; a copy is at ${backup}.`);
823
+ return false;
824
+ }
825
+ }
826
+ /** Add the session checkout. A damaged cache is replaced once, then retried. */
827
+ async addWorktree(cache, input) {
828
+ const { worktree, branch, sessionId } = input;
829
+ const attempt = async (base) => {
830
+ try {
831
+ await this.runGit(['worktree', 'add', worktree, branch], {
832
+ cwd: cache.bare
833
+ });
834
+ }
835
+ catch {
836
+ const existingBranch = await this.runGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: cache.bare }).then(() => true, () => false);
837
+ await this.runGit(existingBranch
838
+ ? ['worktree', 'add', '--detach', worktree, branch]
839
+ : ['worktree', 'add', '-b', branch, worktree, base], { cwd: cache.bare });
840
+ }
841
+ };
842
+ const existedBefore = await (0, promises_1.lstat)(worktree).then(() => true, () => false);
843
+ try {
844
+ await attempt(input.base);
845
+ return;
846
+ }
847
+ catch (error) {
848
+ const kind = (0, repository_cache_1.classifyGitFailure)(error);
849
+ // Remove only what this attempt made: a half-made checkout folder, its
850
+ // registration, and the new branch name.
851
+ if (!existedBefore)
852
+ await (0, promises_1.rm)(worktree, { recursive: true, force: true }).catch(() => undefined);
853
+ await this.runGit(['worktree', 'prune'], { cwd: cache.bare }).catch(() => undefined);
854
+ if (kind !== 'damaged') {
855
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, kind, (0, repository_cache_1.describeFailure)(cache.fullName, kind));
856
+ }
857
+ }
858
+ // Damaged cache: one fresh clone, then one more try.
859
+ this.addNote(sessionId, `Repository ${cache.fullName}: the checkout could not be made from the local copy. Retrying with a fresh clone.`);
860
+ try {
861
+ await this.replaceCache(cache, sessionId);
862
+ const base = await this.prepareCache(cache, input.defaultBranch, sessionId);
863
+ await attempt(base);
864
+ }
865
+ catch (error) {
866
+ if (error instanceof repository_cache_1.RepositoryPrepareError)
867
+ throw error;
868
+ const kind = (0, repository_cache_1.classifyGitFailure)(error);
869
+ throw new repository_cache_1.RepositoryPrepareError(cache.fullName, kind, (0, repository_cache_1.describeFailure)(cache.fullName, kind));
870
+ }
871
+ }
487
872
  async prepare(request) {
488
873
  const sessionRoot = this.sessionPath(request.sessionId);
489
874
  await (0, promises_1.mkdir)(sessionRoot, { recursive: true, mode: 0o700 });
@@ -525,61 +910,32 @@ class GitHubWorkspaceProvider {
525
910
  '-c',
526
911
  `credential.helper=${helper}`
527
912
  ];
528
- try {
529
- await this.runGit(['rev-parse', '--is-bare-repository'], {
530
- cwd: bare
531
- });
532
- }
533
- catch {
534
- await this.runGit([...gitArgs, 'clone', '--bare', transportUrl, bare], {
535
- timeout: 10 * 60_000,
536
- maxBuffer: 10 * 1024 * 1024,
537
- environment: gitNetworkEnvironment
538
- });
539
- await this.runGit([
540
- 'config',
541
- 'remote.origin.fetch',
542
- '+refs/heads/*:refs/remotes/origin/*'
543
- ], { cwd: bare });
544
- }
545
- // The identity check above permits old proxy/sentinel URL forms. Fetch
546
- // through the current lease URL so a stale loopback port cannot fail first.
547
- await this.runGit([
548
- ...gitArgs,
549
- 'fetch',
913
+ const cache = {
914
+ bare,
550
915
  transportUrl,
551
- '+refs/heads/*:refs/remotes/origin/*'
552
- ], {
553
- cwd: bare,
554
- timeout: 10 * 60_000,
555
- maxBuffer: 10 * 1024 * 1024,
556
- environment: gitNetworkEnvironment
557
- });
916
+ gitArgs,
917
+ environment: gitNetworkEnvironment,
918
+ fullName: repository.fullName
919
+ };
558
920
  const branch = `agent/${request.sessionId}`;
559
- const reuse = await this.canReuseWorktree(bare, worktree, repository.cloneUrl, request.sessionId);
560
- if (!reuse) {
561
- try {
562
- await this.runGit(['worktree', 'add', worktree, branch], {
563
- cwd: bare
564
- });
565
- }
566
- catch {
567
- const existingBranch = await this.runGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: bare }).then(() => true, () => false);
568
- await this.runGit(existingBranch
569
- ? ['worktree', 'add', '--detach', worktree, branch]
570
- : [
571
- 'worktree',
572
- 'add',
573
- '-b',
574
- branch,
575
- worktree,
576
- `origin/${repository.defaultBranch}`
577
- ], { cwd: bare });
578
- }
579
- }
580
- else {
921
+ let reuse = false;
922
+ // One preparation per repository cache at a time. Two sessions that
923
+ // start together must not clone, fetch or swap the same cache at once.
924
+ await this.withRepositoryLock(bare, async () => {
925
+ const base = await this.prepareCache(cache, repository.defaultBranch, request.sessionId);
926
+ reuse = await this.canReuseWorktree(bare, worktree, repository.cloneUrl, request.sessionId);
927
+ if (reuse)
928
+ return;
929
+ await this.addWorktree(cache, {
930
+ worktree,
931
+ branch,
932
+ base,
933
+ defaultBranch: repository.defaultBranch,
934
+ sessionId: request.sessionId
935
+ });
936
+ });
937
+ if (reuse)
581
938
  reusedWorktree = true;
582
- }
583
939
  worktrees.push(worktree);
584
940
  await this.runGit(['config', '--unset-all', 'credential.helper'], {
585
941
  cwd: worktree
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Pure helpers for the cached bare clone behind a repository checkout.
3
+ *
4
+ * A cache can be wrong in ways `git rev-parse --is-bare-repository` cannot see:
5
+ * an interrupted first clone, a missing object, a default branch that is not
6
+ * `main`. These helpers sort a Git failure into a small set of kinds, so the
7
+ * workspace can decide whether a fresh clone helps and can tell the user the
8
+ * reason in plain words. They never return Git's raw output: it can carry
9
+ * remote URLs.
10
+ */
11
+ export type GitFailureKind = 'auth' | 'network' | 'damaged' | 'other';
12
+ /** A repository checkout failure with a message that is safe to show. */
13
+ export declare class RepositoryPrepareError extends Error {
14
+ readonly fullName: string;
15
+ readonly kind: GitFailureKind | 'no-default-branch' | 'in-use';
16
+ constructor(fullName: string, kind: GitFailureKind | 'no-default-branch' | 'in-use', message: string);
17
+ }
18
+ /** Sort a failed Git command. Order matters: access problems come first. */
19
+ export declare function classifyGitFailure(error: unknown): GitFailureKind;
20
+ /** The reason shown to the user. No Git output, no URLs, no tokens. */
21
+ export declare function describeFailure(fullName: string, kind: RepositoryPrepareError['kind']): string;
22
+ /** `ref: refs/heads/main\tHEAD` from `git ls-remote --symref <url> HEAD`. */
23
+ export declare function parseRemoteDefaultBranch(output: string): string | null;
24
+ /** Remote branches to try, best first, without repeats. */
25
+ export declare function baseBranchCandidates(input: {
26
+ preferred?: string | null;
27
+ headBranch?: string | null;
28
+ originHeadBranch?: string | null;
29
+ }): string[];
30
+ /** `git version 2.54.0 (Apple Git-157)` -> [2, 54]. Null when unreadable. */
31
+ export declare function parseGitVersion(output: string): [number, number] | null;
32
+ export declare function gitAtLeast(version: [number, number] | null, major: number, minor: number): boolean;
33
+ /** `git clone --ref-format=reftable` needs Git 2.45. */
34
+ export declare const REFTABLE_CLONE_GIT: readonly [2, 45];
35
+ /** `git refs migrate` needs Git 2.46. */
36
+ export declare const REFTABLE_MIGRATE_GIT: readonly [2, 46];
37
+ /**
38
+ * Where branch names can differ only in case, the default `files` ref storage
39
+ * cannot keep them: it stores one file per ref, and two names are one file.
40
+ * Fetch then fails on those refs, and a first clone can stop before it sets
41
+ * HEAD. The `reftable` format keeps refs in one table and has no such limit.
42
+ */
43
+ export declare function shouldUseReftable(input: {
44
+ caseInsensitive: boolean;
45
+ git: [number, number] | null;
46
+ }): boolean;
47
+ export declare function shouldMigrateToReftable(input: {
48
+ caseInsensitive: boolean;
49
+ git: [number, number] | null;
50
+ refFormat: string;
51
+ liveWorktrees: number;
52
+ }): boolean;
53
+ /** The marker file a finished, checked clone carries. */
54
+ export declare const CLONE_MARKER = "pf-clone-complete.json";
@@ -0,0 +1,116 @@
1
+ "use strict";
2
+ /**
3
+ * Pure helpers for the cached bare clone behind a repository checkout.
4
+ *
5
+ * A cache can be wrong in ways `git rev-parse --is-bare-repository` cannot see:
6
+ * an interrupted first clone, a missing object, a default branch that is not
7
+ * `main`. These helpers sort a Git failure into a small set of kinds, so the
8
+ * workspace can decide whether a fresh clone helps and can tell the user the
9
+ * reason in plain words. They never return Git's raw output: it can carry
10
+ * remote URLs.
11
+ */
12
+ Object.defineProperty(exports, "__esModule", { value: true });
13
+ exports.CLONE_MARKER = exports.REFTABLE_MIGRATE_GIT = exports.REFTABLE_CLONE_GIT = exports.RepositoryPrepareError = void 0;
14
+ exports.classifyGitFailure = classifyGitFailure;
15
+ exports.describeFailure = describeFailure;
16
+ exports.parseRemoteDefaultBranch = parseRemoteDefaultBranch;
17
+ exports.baseBranchCandidates = baseBranchCandidates;
18
+ exports.parseGitVersion = parseGitVersion;
19
+ exports.gitAtLeast = gitAtLeast;
20
+ exports.shouldUseReftable = shouldUseReftable;
21
+ exports.shouldMigrateToReftable = shouldMigrateToReftable;
22
+ /** A repository checkout failure with a message that is safe to show. */
23
+ class RepositoryPrepareError extends Error {
24
+ fullName;
25
+ kind;
26
+ constructor(fullName, kind, message) {
27
+ super(message);
28
+ this.fullName = fullName;
29
+ this.kind = kind;
30
+ this.name = 'RepositoryPrepareError';
31
+ }
32
+ }
33
+ exports.RepositoryPrepareError = RepositoryPrepareError;
34
+ function failureText(error) {
35
+ const failure = error;
36
+ return `${typeof failure?.stderr === 'string' ? failure.stderr : ''}\n${typeof failure?.message === 'string' ? failure.message : ''}`;
37
+ }
38
+ /** Sort a failed Git command. Order matters: access problems come first. */
39
+ function classifyGitFailure(error) {
40
+ const text = failureText(error);
41
+ if (/Authentication failed|could not read (Username|Password)|Permission denied|Repository not found|returned error: 40[134]|HTTP[^\n]{0,20}40[134]|access denied/i.test(text))
42
+ return 'auth';
43
+ if (/Could not resolve host|Connection (refused|timed out|reset)|Failed to connect|timed out|early EOF|RPC failed|unable to access|Network is unreachable|ETIMEDOUT/i.test(text))
44
+ return 'network';
45
+ if (/failed to resolve|invalid reference|unable to read tree|bad object|missing (blob|tree|commit)|not a valid object|corrupt|loose object|packfile|index file|not a git repository|did not match any|unable to read|bad revision|does not have any commits|remote end hung up/i.test(text))
46
+ return 'damaged';
47
+ return 'other';
48
+ }
49
+ /** The reason shown to the user. No Git output, no URLs, no tokens. */
50
+ function describeFailure(fullName, kind) {
51
+ switch (kind) {
52
+ case 'auth':
53
+ return `Repository ${fullName} was not checked out: GitHub refused access. Check that the GitHub App can read this repository, then send the message again.`;
54
+ case 'network':
55
+ return `Repository ${fullName} was not checked out: GitHub could not be reached from this computer. Check the network, then send the message again.`;
56
+ case 'damaged':
57
+ return `Repository ${fullName} was not checked out: the local copy is damaged and a fresh clone did not fix it. Send the message again. If it still fails, move the repository cache folder aside.`;
58
+ case 'no-default-branch':
59
+ return `Repository ${fullName} was not checked out: no default branch was found. The repository may be empty. Push a first commit, then send the message again.`;
60
+ case 'in-use':
61
+ return `Repository ${fullName} was not checked out: its local copy is damaged and another session is using it. Finish that session, then send the message again.`;
62
+ default:
63
+ return `Repository ${fullName} was not checked out: Git failed. Send the message again. If it still fails, check the harness log.`;
64
+ }
65
+ }
66
+ /** `ref: refs/heads/main\tHEAD` from `git ls-remote --symref <url> HEAD`. */
67
+ function parseRemoteDefaultBranch(output) {
68
+ const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD\s*$/m.exec(output);
69
+ return match ? match[1] : null;
70
+ }
71
+ /** Remote branches to try, best first, without repeats. */
72
+ function baseBranchCandidates(input) {
73
+ const list = [
74
+ input.preferred,
75
+ input.headBranch,
76
+ input.originHeadBranch,
77
+ 'main',
78
+ 'master'
79
+ ].filter((name) => Boolean(name && name.trim()));
80
+ return [...new Set(list)];
81
+ }
82
+ /* ------------------------------------------------------------------ */
83
+ /* Ref storage and completion */
84
+ /* ------------------------------------------------------------------ */
85
+ /** `git version 2.54.0 (Apple Git-157)` -> [2, 54]. Null when unreadable. */
86
+ function parseGitVersion(output) {
87
+ const match = /(\d+)\.(\d+)/.exec(output);
88
+ return match ? [Number(match[1]), Number(match[2])] : null;
89
+ }
90
+ function gitAtLeast(version, major, minor) {
91
+ if (!version)
92
+ return false;
93
+ return version[0] > major || (version[0] === major && version[1] >= minor);
94
+ }
95
+ /** `git clone --ref-format=reftable` needs Git 2.45. */
96
+ exports.REFTABLE_CLONE_GIT = [2, 45];
97
+ /** `git refs migrate` needs Git 2.46. */
98
+ exports.REFTABLE_MIGRATE_GIT = [2, 46];
99
+ /**
100
+ * Where branch names can differ only in case, the default `files` ref storage
101
+ * cannot keep them: it stores one file per ref, and two names are one file.
102
+ * Fetch then fails on those refs, and a first clone can stop before it sets
103
+ * HEAD. The `reftable` format keeps refs in one table and has no such limit.
104
+ */
105
+ function shouldUseReftable(input) {
106
+ return (input.caseInsensitive &&
107
+ gitAtLeast(input.git, exports.REFTABLE_CLONE_GIT[0], exports.REFTABLE_CLONE_GIT[1]));
108
+ }
109
+ function shouldMigrateToReftable(input) {
110
+ return (input.caseInsensitive &&
111
+ input.refFormat === 'files' &&
112
+ input.liveWorktrees === 0 &&
113
+ gitAtLeast(input.git, exports.REFTABLE_MIGRATE_GIT[0], exports.REFTABLE_MIGRATE_GIT[1]));
114
+ }
115
+ /** The marker file a finished, checked clone carries. */
116
+ exports.CLONE_MARKER = 'pf-clone-complete.json';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peakflo/agent-harness",
3
- "version": "0.2.26-rc.1",
3
+ "version": "0.2.27-rc.1",
4
4
  "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",