Refusing terminal workspace cleanup because the expected…

Error message

Refusing terminal workspace cleanup because the expected git HEAD is unknown

What it means

Fail-closed safety check in assertTerminalCleanupGitStateUnchanged: a git_worktree workspace is about to be terminally cleaned up, but either its local path or the expected HEAD SHA (workspaceHeadSha captured when delivery was verified) is unknown. Without a pinned expected HEAD the 'unchanged since verification' invariant cannot be checked, so destructive cleanup is refused.

Solutions

Restore the expected git HEAD record for the workspace before cleanup, or clean up the workspace manually.

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/src/services/execution-workspaces.ts:1446 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/c2186368230f6619. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/execution-workspaces.ts:1452

            && workspaceHeadSha !== null
          ) {
            mergedPullRequest = true;
            break;
          }
          if (
            details.state === "unknown"
            || (details.state === "merged" && (!details.headRef || !details.headSha || !workspaceHeadSha))
          ) {
            pullRequestStateUnknown = true;
          }
        }
        if (mergedPullRequest) break;
      }
    }

    return {
      deliveryState: deriveExecutionWorkspaceDeliveryState({
        sourceIssueTerminal,
        mergedPullRequest,
        pullRequestStateUnknown,
        isMergedIntoBase: git?.isMergedIntoBase ?? null,
      }),
      sourceIssueTerminal,
      subtreeTerminal,
      cooldownAnchor,
      workspaceDirty: Boolean(git?.hasDirtyTrackedFiles || git?.hasUntrackedFiles),
      workspaceHeadSha,
    };
  }

  async function assertTerminalCleanupGitStateUnchanged(
    workspace: ExecutionWorkspaceRow,
    expectedHeadSha: string | null,
  ) {
    if (workspace.providerType !== "git_worktree") return;
    const workspacePath = readNullableString(workspace.providerRef) ?? readNullableString(workspace.cwd);

View on GitHub (pinned to 3f1d897a7c)