@ricsam/r5d-worker 0.0.74 → 0.0.76

package/dist/types/main.d.ts

@@ -1,5 +1,17 @@
 #!/usr/bin/env bun
-import { type WorkspaceProjectManifestEntry } from "./workspace-sync";
+type WorkerProjectConfig = {
+    projectId: string;
+    checkoutPathSegments: [namespace: string, project: string];
+    projectPath: string;
+    repoHttpUrl: string | null;
+    repoAuthHeader: string | null;
+    defaultBranch: string;
+    branches: Array<{
+        branchName: string;
+        sourceBranchName: string | null;
+        baseCommitHash: string;
+    }>;
+};
 export type WorkerSessionTarget = {
     type: "project";
     projectId: string;
@@ -21,7 +33,6 @@ type WorkerReadFileResult = {
     truncated: boolean;
     continuation?: string;
 };
-type WorkerProjectManifestEntry = WorkspaceProjectManifestEntry;
 type WorkerWriteFileResult = {
     type: "write";
     file: string;
@@ -60,6 +71,24 @@ type WorkerViewFileBytesResult = {
     width: number;
     height: number;
 };
+type WorkerCodeEntry = {
+    name: string;
+    type: "file" | "directory";
+    size: number | null;
+    mtime: string;
+};
+type WorkerCodeListResult = {
+    type: "code_list";
+    path: string;
+    entries: WorkerCodeEntry[];
+};
+type WorkerCodeReadResult = {
+    type: "code_read";
+    path: string;
+    size: number;
+    mtime: string;
+    base64: string;
+};
 export type WorkerBuiltInToolPaths = {
     artifactsDir?: string;
     plansDir?: string;
@@ -83,17 +112,6 @@ export declare function preparePlanEnvForShell(input: {
     planRoot: string;
     activePlanId?: string;
 }): Record<string, string>;
-type GitAuth = {
-    extraHeaderUrl: string;
-    header: string;
-};
-declare function gitAuthArgs(auth?: GitAuth): string[];
-export declare const visibleCheckoutGitTestHarness: {
-    gitAuthArgs: typeof gitAuthArgs;
-    commandArgs: (args: string[], auth?: GitAuth) => string[];
-    cloneArgs: (remoteUrl: string, branchPath: string) => string[];
-    fetchArgs: (...args: string[]) => string[];
-};
 type ResolvedWorkerFilePath = {
     absolutePath: string;
     displayPath: string;
@@ -112,59 +130,19 @@ type ResolvedWorkerFilePath = {
     virtualRootPath: string;
 };
 export declare function resolveWorkerFilePath(branchPath: string, inputPath: string, builtInPaths?: WorkerBuiltInToolPaths): ResolvedWorkerFilePath;
-export declare function visibleCheckoutRemoteFor(input: {
-    baseUrl: string;
-    token: string;
-    projectId: string;
-    branchName: string;
-    manifest?: WorkerProjectManifestEntry;
-}): {
-    remoteUrl: string;
-    authHeader: string | null;
-    persistAuth: boolean;
-    reconcileExistingOrigin: boolean;
-    requireRemoteBranch: boolean;
-    requiredBaseCommit: string | null;
-};
 export declare function githubCliEnv(token: string | null | undefined): Record<string, string>;
-export declare function ensureVisibleGitCheckout(input: {
-    projectRoot: string;
-    branchName: string;
-    remoteUrl: string;
-    remoteAuth?: GitAuth;
-    persistentAuthHeader?: string | null;
-    defaultBranch: string;
-    reconcileExistingOrigin?: boolean;
-    requireRemoteBranch?: boolean;
-    requiredBaseCommit?: string | null;
-    allowRequiredRemoteMigration?: boolean;
-    clearPersistentAuth?: boolean;
-}): string;
 type ResolvedWorkerSessionTarget = {
     target: WorkerSessionTarget;
     rootPath: string;
-    manifest?: WorkerProjectManifestEntry;
+    config?: WorkerProjectConfig;
 };
 export declare function describeWorkerSessionTarget(target: WorkerSessionTarget): string;
 export declare function resolveWorkerSessionTarget(input: {
     target: WorkerSessionTarget;
-    baseUrl: string;
-    token: string;
     projectsRoot: string;
-    syncRoot: string;
     workspaceShadowRoot: string;
-    manifestByProjectId: Map<string, WorkerProjectManifestEntry>;
+    projectConfigById: Map<string, WorkerProjectConfig>;
 }): ResolvedWorkerSessionTarget;
-type VisibleCheckoutTarget = {
-    projectId: string;
-    branchName: string;
-};
-export declare function workspaceSyncCheckoutTargets(input: {
-    projects: readonly WorkspaceProjectManifestEntry[];
-    pendingTargets: readonly VisibleCheckoutTarget[];
-    includeAllManifestCheckouts: boolean;
-    canonicalCheckoutOnly?: VisibleCheckoutTarget;
-}): VisibleCheckoutTarget[];
 export declare function prepareBuiltInToolPathsForTarget(input: {
     target: WorkerSessionTarget;
     filePath: string;
@@ -196,6 +174,8 @@ export declare function findWorkerFiles(branchPath: string, input: {
     limit?: number;
 }, builtInPaths?: WorkerBuiltInToolPaths): WorkerFindResult;
 export declare function listWorkerDirectory(branchPath: string, inputPath?: string, inputLimit?: number, builtInPaths?: WorkerBuiltInToolPaths): WorkerLsResult;
+export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): WorkerCodeListResult;
+export declare function readWorkerCodeFile(branchPath: string, inputPath: string): WorkerCodeReadResult;
 export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerViewFileBytesResult;
 export declare function prepareShellEnvForTarget(input: {
     target: WorkerSessionTarget;

package/dist/types/project-workspace-state.d.ts

@@ -0,0 +1,144 @@
+import { type CheckoutPathSegments } from "./managed-paths";
+export declare const PROJECT_WORKSPACE_STATE_FILE = "project-workspace-state.json";
+export type ProjectWorkspaceDesiredProjectInput = {
+    projectId: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    defaultBranch: string;
+    branches: readonly {
+        branchName: string;
+    }[];
+};
+export type ProjectWorkspaceDesiredProject = {
+    projectId: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    defaultBranch: string;
+    branches: Array<{
+        branchName: string;
+    }>;
+};
+export type LocallyPendingCreatedProjectBranch = {
+    projectId: string;
+    branchName: string;
+};
+type ProjectWorkspaceDeletionBase = {
+    id: string;
+    projectId: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    treePublishedHead: string | null;
+    mirrorRefsDeleted: string[];
+};
+export type ProjectWorkspaceBranchDeletionTombstone = ProjectWorkspaceDeletionBase & {
+    kind: "branch";
+    branchName: string;
+};
+export type ProjectWorkspaceProjectDeletionTombstone = ProjectWorkspaceDeletionBase & {
+    kind: "project";
+    branchNames: string[];
+};
+export type ProjectWorkspaceDeletionTombstone = ProjectWorkspaceBranchDeletionTombstone | ProjectWorkspaceProjectDeletionTombstone;
+export type PendingProjectWorkspaceTreeDeletion = {
+    tombstoneId: string;
+    kind: "branch";
+    projectId: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    branchName: string;
+    managedPath: string;
+    primaryBranchName: string | null;
+} | {
+    tombstoneId: string;
+    kind: "project";
+    projectId: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    branchNames: string[];
+    managedPath: string;
+    projectDeleted: boolean;
+};
+export type PendingProjectMirrorRefDeletion = {
+    tombstoneId: string;
+    projectId: string;
+    branchName: string;
+    checkoutPathSegments: CheckoutPathSegments;
+    managedPath: string;
+    primaryBranchName: string | null;
+    treePublishedHead: string;
+};
+export type ProjectWorkspaceStateView = {
+    desiredProjects: ProjectWorkspaceDesiredProject[];
+    effectiveDesiredProjects: ProjectWorkspaceDesiredProject[];
+    locallyPendingCreatedBranches: LocallyPendingCreatedProjectBranch[];
+    tombstones: ProjectWorkspaceDeletionTombstone[];
+    pendingTreeDeletions: PendingProjectWorkspaceTreeDeletion[];
+    pendingMirrorRefDeletions: PendingProjectMirrorRefDeletion[];
+};
+export type StaleOuterProjectWorkspaceBranch = {
+    kind: "branch";
+    projectId: string;
+    branchName: string;
+    projectTreePath: string | null;
+    planTreePath: string | null;
+};
+export type StaleOuterProjectWorkspaceProject = {
+    kind: "project";
+    projectId: string;
+    projectTreePath: string | null;
+    planTreePath: string | null;
+    branches: Array<{
+        branchName: string;
+        projectTreePath: string | null;
+        planTreePath: string | null;
+    }>;
+};
+export type StaleOuterProjectWorkspaceEntry = StaleOuterProjectWorkspaceBranch | StaleOuterProjectWorkspaceProject;
+/**
+ * A fresh authoritative configuration wins over any deletion staged by an
+ * older configuration. Remove only exact project/branch targets so unrelated
+ * cleanup (including an old checkout-path tombstone) remains durable.
+ */
+export declare function pruneAuthoritativelyDesiredBranchDeletions<T extends LocallyPendingCreatedProjectBranch>(pendingDeletions: Map<string, T>, desiredProjects: readonly ProjectWorkspaceDesiredProjectInput[]): void;
+/**
+ * Discover legacy outer-tree entries without trusting or walking arbitrary
+ * filesystem names. Only canonical managed project ids and encoded branch
+ * directory names are returned; symlinks, files, and non-layout entries are
+ * deliberately left for an operator.
+ */
+export declare function discoverStaleOuterProjectWorkspaceEntries(input: {
+    workspaceShadowRoot: string;
+    desiredProjects: readonly ProjectWorkspaceDesiredProjectInput[];
+    locallyPendingCreatedBranches?: readonly LocallyPendingCreatedProjectBranch[];
+}): StaleOuterProjectWorkspaceEntry[];
+/**
+ * Durable worker-local ledger for desired project mounts and ordered deletion
+ * side effects. The caller must remove each managed path before including its
+ * tombstone in an outer-tree publication. Mirror refs may be acknowledged only
+ * after that publication is durably recorded.
+ */
+export declare class ProjectWorkspaceStateStore {
+    readonly stateRoot: string;
+    readonly projectsRoot: string;
+    readonly statePath: string;
+    constructor(input: {
+        stateRoot: string;
+        projectsRoot: string;
+    });
+    read(): ProjectWorkspaceStateView;
+    discoverStaleOuterEntries(workspaceShadowRoot: string): StaleOuterProjectWorkspaceEntry[];
+    reconcile(input: {
+        desiredProjects: readonly ProjectWorkspaceDesiredProjectInput[];
+        locallyPendingCreatedBranches?: readonly LocallyPendingCreatedProjectBranch[];
+    }): ProjectWorkspaceStateView;
+    /** Persist the create intent before invoking Git so a crash cannot orphan an untracked worktree. */
+    recordPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    /** Clear a create intent after an authoritative desired config contains it. */
+    clearPendingCreatedBranch(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    /** Persist a branch tombstone before mutating its linked worktree or local ref. */
+    beginBranchDeletion(input: LocallyPendingCreatedProjectBranch): ProjectWorkspaceStateView;
+    recordTreePublication(input: {
+        tombstoneIds: readonly string[];
+        publishedHead: string;
+    }): ProjectWorkspaceStateView;
+    recordMirrorRefDeletion(input: {
+        tombstoneId: string;
+        branchName: string;
+    }): ProjectWorkspaceStateView;
+}
+export {};

package/dist/types/project-worktrees.d.ts

@@ -0,0 +1,112 @@
+export declare const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
+export type GitHttpAuth = {
+    extraHeaderUrl: string;
+    header: string;
+};
+export type ProjectWorktreeBranch = {
+    branchName: string;
+    baseCommitHash: string;
+    sourceBranchName?: string | null;
+};
+export type ProjectWorktreeState = {
+    branchName: string;
+    branchPath: string;
+    head: string;
+    mirrorHead: string | null;
+    ahead: number | null;
+    behind: number | null;
+};
+export declare function projectWorktreeConfigurationFingerprint(input: {
+    checkoutPathSegments: readonly string[];
+    projectPath: string;
+    repoHttpUrl: string | null;
+    repoAuthHeader: string | null;
+    defaultBranch: string;
+    branches: readonly ProjectWorktreeBranch[];
+    gitIdentity: {
+        name: string;
+        email: string;
+    } | null;
+}): string;
+export declare function hasLinkedProjectWorktreeLayout(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branches: readonly Pick<ProjectWorktreeBranch, "branchName">[];
+}): boolean;
+export declare function cleanupStaleProjectWorktreeSnapshots(input?: {
+    temporaryRoot?: string;
+    processAlive?: (processId: number) => boolean;
+}): {
+    removed: string[];
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+};
+export declare function ensureProjectWorktrees(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branches: readonly ProjectWorktreeBranch[];
+    originUrl: string;
+    originAuth?: GitHttpAuth;
+    mirrorUrl: string;
+    mirrorAuth?: GitHttpAuth;
+    credentialHelper?: string | null;
+    gitIdentity?: {
+        name: string;
+        email: string;
+    } | null;
+}): ProjectWorktreeState[];
+export declare function projectWorktreeOperationInProgress(checkoutPath: string): boolean;
+export declare function createLinkedProjectBranch(input: {
+    projectRoot: string;
+    sourceBranchName: string;
+    branchName: string;
+}): {
+    branchPath: string;
+    baseCommitHash: string;
+};
+export declare function deleteLinkedProjectBranch(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branchName: string;
+}): {
+    branchName: string;
+};
+export declare function removeProjectWorktrees(input: {
+    projectRoot: string;
+    branchNames: readonly string[];
+}): void;
+export declare function deleteProjectMirrorBranch(input: {
+    gitDirectory: string;
+    branchName: string;
+    mirrorUrl: string;
+    mirrorAuth?: GitHttpAuth;
+}): void;
+export declare function pushProjectMirrorHeads(input: {
+    projectRoot: string;
+    branchNames: readonly string[];
+    mirrorUrl: string;
+    mirrorAuth?: GitHttpAuth;
+    onlyBranches?: ReadonlySet<string>;
+}): Array<{
+    branchName: string;
+    head: string;
+    pushed: boolean;
+    reason?: string;
+}>;
+export declare function fastForwardProjectHeadsFromMirror(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branchNames: readonly string[];
+    mirrorUrl: string;
+    mirrorAuth?: GitHttpAuth;
+}): Array<{
+    branchName: string;
+    previousHead: string;
+    mirrorHead: string | null;
+    fastForwarded: boolean;
+}>;
+export declare const projectWorktreesTestHarness: {
+    commandArgs: (args: string[], auth?: GitHttpAuth) => string[];
+};

package/dist/types/working-tree-mirror.d.ts

@@ -0,0 +1,24 @@
+export type WorkingTreeSourceMode = "all" | "git";
+export type WorkingTreeDeletionMode = "all" | "git";
+type TreeEntry = {
+    kind: "directory";
+    mode: number;
+} | {
+    kind: "file";
+    mode: number;
+    size: number;
+} | {
+    kind: "symlink";
+    mode: number;
+    target: string;
+};
+export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode): Map<string, TreeEntry>;
+export declare function mirrorWorkingTree(input: {
+    sourceRoot: string;
+    targetRoot: string;
+    sourceMode: WorkingTreeSourceMode;
+    deletionMode: WorkingTreeDeletionMode;
+}): {
+    paths: string[];
+};
+export {};

package/dist/types/workspace-git-sync.d.ts

@@ -0,0 +1,97 @@
+import { type WorkingTreeSourceMode } from "./working-tree-mirror";
+import type { GitHttpAuth } from "./project-worktrees";
+export declare const WORKSPACE_GIT_BRANCH = "main";
+export declare const MAX_WORKSPACE_GIT_DIFF_BYTES: number;
+export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v1";
+export type WorkspaceGitMount = {
+    id: string;
+    sourcePath: string;
+    workspaceRelativePath: string;
+    sourceMode: WorkingTreeSourceMode;
+    hydrateDeletionMode: "all" | "git";
+    /** Remove the outer-workspace subtree when the mounted source was intentionally deleted. */
+    deleteWhenSourceMissing?: boolean;
+    busy?: () => boolean;
+};
+export type WorkspaceGitSyncOutcome = "no_change" | "updated" | "pushed" | "large_diff_blocked" | "conflict_blocked";
+export type WorkspaceGitSyncResult = {
+    outcome: WorkspaceGitSyncOutcome;
+    startingHead: string | null;
+    /** The worker-local commit, including an unpublished blocked commit. */
+    localHead: string | null;
+    remoteHead: string | null;
+    publishedHead: string | null;
+    rebaseCount: number;
+    diffSizeBytes: number;
+    affectedPaths: string[];
+    activeMountIds: string[];
+    skippedMountIds: string[];
+    conflictPaths?: string[];
+    conflictSnapshotRefs?: {
+        local: string;
+        remote: string;
+    };
+    error?: string;
+};
+export declare function ensureWorkspaceGitClone(input: {
+    workspacePath: string;
+    remoteUrl: string;
+    remoteAuth?: GitHttpAuth;
+    credentialHelper?: string | null;
+    gitIdentity: {
+        name: string;
+        email: string;
+    };
+}): {
+    localHead: string | null;
+    remoteHead: string | null;
+};
+declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
+export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
+export declare function resetWorkspaceGit(input: {
+    workspacePath: string;
+    remoteUrl: string;
+    remoteAuth?: GitHttpAuth;
+    credentialHelper?: string | null;
+    gitIdentity: {
+        name: string;
+        email: string;
+    };
+    mounts: readonly WorkspaceGitMount[];
+}): {
+    startingHead: string | null;
+    localHead: string | null;
+    remoteHead: string | null;
+    discardedPaths: string[];
+};
+export declare function synchronizeWorkspaceGit(input: {
+    attemptId?: string;
+    workerLabel: string;
+    workspacePath: string;
+    remoteUrl: string;
+    remoteAuth?: GitHttpAuth;
+    credentialHelper?: string | null;
+    gitIdentity: {
+        name: string;
+        email: string;
+    };
+    mounts: readonly WorkspaceGitMount[];
+    commitDetail?: string;
+    allowLargeDiff?: boolean;
+    maxDiffBytes?: number;
+    maxPushAttempts?: number;
+    /** Publish edits already made in the outer clone without first projecting visible mounts over them. */
+    skipMountMirror?: boolean;
+    /** Leave visible mounts untouched after publication (used by remediation commands in the outer clone). */
+    skipMountHydration?: boolean;
+    afterWorkspacePublished?: (context: {
+        publishedHead: string;
+        activeMountIds: string[];
+    }) => void | Promise<void>;
+}): Promise<WorkspaceGitSyncResult>;
+export declare const workspaceGitSyncTestHarness: {
+    commandArgs: (args: string[], auth?: GitHttpAuth) => string[];
+    mirrorMountsToWorkspace: typeof mirrorMountsToWorkspace;
+    hydrateMountsFromWorkspace: typeof hydrateWorkspaceGitMounts;
+};
+export {};

package/dist/types/workspace-incident-state.d.ts

@@ -2,21 +2,4 @@ export type WorkspaceIncidentUpdate = {
     incidentId: string | null;
     status: "remediating" | "waiting_for_worker" | "resolved" | "confirmed" | "reset" | null;
 };
-/**
- * WebSocket writes are ordered, but independent server handlers can decide an
- * incident state under the user lock and write their messages after releasing
- * it. Remember terminal incident IDs so a delayed publication response cannot
- * resurrect a barrier that this connection has already observed as terminal.
- */
-export declare class WorkspaceIncidentOrderingFence {
-    private readonly historyLimit;
-    private readonly terminalIncidentIds;
-    private readonly terminalIncidentOrder;
-    constructor(historyLimit?: number);
-    observe(update: WorkspaceIncidentUpdate): void;
-    permitsBlockedResponse(incidentId: string | null | undefined): boolean;
-}
 export declare function applyWorkspaceIncidentUpdate(currentIncidentId: string | null, update: WorkspaceIncidentUpdate): string | null;
-export declare function releasePendingWorkspaceHead(previousIncidentId: string | null, currentIncidentId: string | null, terminalIncidentId?: string | null): {
-    fetchAuthoritativeHead: boolean;
-};

package/dist/types/workspace-mutation-gate.d.ts

@@ -1,12 +1,12 @@
 export type WorkspaceMutationLease = () => void;
 /**
- * Coordinates the visible workspace with its disposable sync shadow.
+ * Coordinates project worktrees with the outer workspace Git clone.
  *
  * Ordinary worktree activity may overlap other ordinary activity, but a sync
  * gets exclusive access. Once a sync is queued, later mutations wait behind it
  * so a queued sync cannot be starved by later short mutations. Long-running
- * visible-checkout commands do not enter this gate; canonical remediation
- * commands do because they operate on the sync checkout itself.
+ * long-running project commands do not enter this gate; outer-workspace
+ * remediation commands do because they operate on the sync clone itself.
  */
 export declare class WorkspaceMutationGate {
     private activeMutations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.74",
+  "version": "0.0.76",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",