paperclipai/paperclip · warning · Error

Could not clean managed GitHub launchers

Error message

Could not clean managed GitHub launchers

What it means

After execution settles, the managed GitHub launcher directory is removed: on remote targets via `sh -c 'rm -rf -- <dir>'` executed through the target's command runner, locally via fs.rm. A non-zero exit code from the remote rm raises this error, meaning stale launcher files may remain on the remote host.

Source

Thrown at packages/adapter-utils/src/execution-target.ts:1543

};

function githubOperationLauncherDirectory(input: GitHubLauncherLocation): string {
  // Only controller-generated run IDs may name a removable directory.
  if (!/^[a-zA-Z0-9_-]+$/.test(input.runId)) throw new Error("Invalid GitHub launcher run ID");
  return input.target?.kind === "remote"
    ? path.posix.join(input.target.remoteCwd, ".paperclip-runtime", "github", input.runId)
    : path.join(os.tmpdir(), "paperclip-github-runtime", input.runId);
}

/** Call only after execution settles, before releasing its remote environment lease. */
export async function cleanupGitHubOperationLaunchers(input: GitHubLauncherLocation): Promise<void> {
  const directory = githubOperationLauncherDirectory(input);
  if (input.target?.kind === "remote") {
    const result = await adapterExecutionTargetCommandRunner(input.target).execute({
      command: "sh", args: ["-c", `rm -rf -- ${shellQuote(directory)}`],
      cwd: input.target.remoteCwd, timeoutMs: 5_000,
    });
    if (result.exitCode !== 0) throw new Error("Could not clean managed GitHub launchers");
  } else {
    await fs.rm(directory, { recursive: true, force: true });
  }
}

async function githubOperationLauncherBasePath(
  target: AdapterCommandCapableExecutionTarget | null,
  env: Record<string, string>,
): Promise<string> {
  if (!target) return env.PATH || process.env.PATH || "/usr/bin:/bin";
  const configuredPath = sanitizeRemoteExecutionEnv(env).PATH;
  if (configuredPath !== undefined) return configuredPath;

  // The provider owns login/profile setup. Query its effective PATH before
  // staging BASH_ENV, rather than substituting the controller's toolchain or
  // a minimal PATH that hides legacy NVM/user-local agent installations.
  const result = await adapterExecutionTargetCommandRunner(target).execute({
    command: "sh",

View on GitHub (pinned to 01ad858492)

Solutions

  1. SSH into the remote target and manually run `rm -rf <remoteCwd>/.paperclip-runtime/github/<runId>` to clear the stale directory
  2. Check remote disk space and permissions on .paperclip-runtime
  3. Retry the cleanup after the remote environment is healthy and no processes hold the files

Example fix

// manual remediation on remote host
ssh user@remote 'rm -rf ~/repo/.paperclip-runtime/github/<runId>'
Defensive patterns

Strategy: retry

Validate before calling

const probe = await runner.execute({ command: 'sh', args: ['-c', 'test -d <dir> && test -w <dir>'], timeoutMs: 5000 });
if (probe.exitCode !== 0) console.warn('launcher dir missing or not writable; cleanup will no-op/fail');

Try / catch

try {
  await cleanManagedLaunchers(input);
} catch (e) {
  if (String(e.message).includes('Could not clean managed GitHub launchers')) {
    console.warn('remote cleanup failed; remove the directory manually later');
  } else throw e;
}

Prevention

When it happens

Trigger: Remote rm -rf fails due to insufficient permissions on the directory, a read-only or full remote filesystem, the directory being locked by a still-running process, or SSH/connection problems yielding a non-zero exit.

Common situations: Remote CI host with a full disk; launcher directory owned by a different user after a permission change; remote lease released while processes still hold files; flaky SSH connection during cleanup.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/5d7bf572596fb70b. Report an issue: GitHub.