@link-assistant/hive-mind 1.75.0 → 1.76.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @link-assistant/hive-mind
 
+## 1.76.1
+
+### Patch Changes
+
+- 13e7e6a: Docker isolation: reuse the host image instead of re-downloading a copy inside the (nested) Docker daemon (#1879).
+  - src/isolation-runner.lib.mjs: add `HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG` to pin the
+    isolation image tag, and `HIVE_MIND_DOCKER_ISOLATION_PULL` (always|missing|never) to emit a
+    `docker run --pull` policy. Verbose mode now logs the resolved image and pull policy.
+  - scripts/preload-dind-isolation-image.mjs: seed a DinD container's nested daemon from the
+    host (`docker save | docker exec -i … docker load`) so isolated tasks reuse the host image.
+  - .env.example: document the Docker isolation image/pull controls.
+  - Dockerfile / Dockerfile.dind / coolify/Dockerfile: bump the box base images to
+    `konard/box:2.2.0` / `konard/box-dind:2.2.0` (and the `docs/UBUNTU-SERVER*.md` examples).
+    v2.2.0 ships box's native host-image passthrough (box#94/#95), so the DinD deployment can seed
+    the nested daemon from the host automatically with
+    `-v /var/run/docker.sock:/var/run/host-docker.sock:ro -e DIND_HOST_PASSTHROUGH=public`.
+  - tests/test-issue-1879-docker-image-reuse.mjs: regression coverage.
+  - docs/case-studies/issue-1879: deep case study with logs, timeline, root causes, and runbook;
+    records that box#94 shipped in v2.2.0 and reports two upstream follow-ups — box#96
+    (public-mode passthrough test false positive) and box#97 (per-repository passthrough allowlist).
+
+- 7335a73: Continue fork PRs with "Allow edits by maintainers" instead of halting on a misclassified fork divergence (#1893).
+
+  When the solver continues a cross-repository PR opened from another contributor's fork, it
+  synced the upstream default branch and then tried to push it back to `origin` — the
+  contributor's fork, which the operating maintainer does not own. GitHub rejected the push
+  with `! [remote rejected] main -> main (permission denied)`, and the solver misclassified
+  that permission error as a fork divergence (the heuristic matched the substring `rejected`),
+  halting with `Repository setup halted - fork divergence requires user decision` and advising
+  `--allow-fork-divergence-resolution-using-force-push-with-lease` — a flag that cannot help,
+  since force-push also requires fork write access.
+  - src/solve.branch-divergence.lib.mjs: add two pure helpers —
+    `shouldPushDefaultBranchToFork({currentUser, forkedRepo})` (skip the push when the user does
+    not own the fork; fail-open when owner/user is unknown) and `isPermissionDeniedPushError()`
+    (recognize a permission-denied rejection so it is never treated as divergence).
+  - src/solve.fork-sync.lib.mjs: new module holding `setupUpstreamAndSync` (extracted from
+    solve.repository.lib.mjs to stay under the 1500-line limit, re-exported unchanged). It now
+    resolves the current user, skips the fork's default-branch push when the user is not the fork
+    owner, and on a permission-denied push warns and continues on the PR branch instead of
+    halting. Genuine non-fast-forward divergence still triggers the original guidance. Adds
+    verbose diagnostics explaining each skip/continue decision.
+  - tests/test-issue-1893-fork-pr-permission-denied.mjs: regression coverage (9 cases) using the
+    exact failure output from the run log.
+  - docs/case-studies/issue-1893: deep case study with downloaded logs/data, timeline, root
+    causes, fix, codebase-wide audit, and existing-components review.
+
+## 1.76.0
+
+### Minor Changes
+
+- 80c56fa: Add experimental `--use-handoff` HANDOFF.md continuity **Agent Skill** (issue
+  #1877). When enabled, Hive Mind deploys a real `SKILL.md` (the Agent Skills open
+  standard created by Anthropic) into the session working directory for both tools
+  natively — `.claude/skills/handoff/SKILL.md` for `--tool claude` and
+  `.agents/skills/handoff/SKILL.md` for `--tool codex` — so the very same skill
+  teaches each tool to read `HANDOFF.md` (repository root) first when present and
+  keep it updated with task, current state, decisions, next steps, gotchas, and
+  critical files. A minimal activation nudge in the system prompt ensures the
+  read-at-session-start behavior fires reliably. Because each Hive Mind working
+  session runs in an ephemeral working directory cloned from the PR branch, the
+  handoff file is committed to the branch — making it the shared cross-session,
+  cross-tool memory so Claude and Codex can continue each other's work in a single
+  pull request. The deployed `SKILL.md` is tooling (re-deployed every session) and
+  is kept out of the target repository via `.git/info/exclude`, so it never appears
+  in the PR. Disabled by default; auto-forwarded by `hive`. Includes a case study
+  in `docs/case-studies/issue-1877/` and tests in `tests/handoff-prompt.test.mjs`.
+
 ## 1.75.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.75.0",
+  "version": "1.76.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/claude.lib.mjs

@@ -28,6 +28,7 @@ import { fetchModelInfo } from './model-info.lib.mjs';
 import { classifyRetryableError, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
 import { resolveSubSessionSize } from './sub-session-size.lib.mjs'; // Issue #1706
 import { withAgentsMdAsClaudeMd } from './agents-md-claude-support.lib.mjs';
+import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
 import { createThinkingBlockRecovery } from './claude.thinking-block-recovery.lib.mjs'; // Issue #1834 (PR #1835 feedback)
 export { availableModels, fetchModelInfo }; // Re-export for backward compatibility
 const showResumeCommand = async (sessionId, tempDir, claudePath, model, log, argv = null) => {
@@ -353,6 +354,10 @@ export const executeClaude = async params => {
   const escapedPrompt = prompt.replace(/"/g, '\\"').replace(/\$/g, '\\$');
   const escapedSystemPrompt = systemPrompt.replace(/"/g, '\\"').replace(/\$/g, '\\$');
 
+  // Issue #1877: deploy the experimental HANDOFF.md Agent Skill so Claude loads
+  // it natively from .claude/skills/handoff/SKILL.md (no-op unless --use-handoff).
+  await deployHandoffSkill({ tempDir, argv, log, $ });
+
   return await withAgentsMdAsClaudeMd({ tempDir, branchName, argv, prompt, fs, path, $, log, formatAligned }, () =>
     executeClaudeCommand({
       tempDir,

package/src/claude.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getHandoffSubPrompt } from './handoff.prompts.lib.mjs';
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { primaryModelNames } from './models/index.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
@@ -338,7 +339,7 @@ Visual UI work and screenshots.
    - When the fix is visual, include side-by-side or sequential comparison of before/after states in the PR description.
    - When possible, create automated visual regression tests to prevent the UI bug from recurring.`
        : ''
-   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${buildWorkLanguageDirective()}`;
+   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${getHandoffSubPrompt(argv)}${buildWorkLanguageDirective()}`;
 };
 
 // Export all functions as default object too

package/src/codex.lib.mjs

@@ -29,6 +29,7 @@ import { defaultModels } from './models/index.mjs';
 import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
+import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
 import Decimal from 'decimal.js-light';
 
 const CODEX_USAGE_FIELD_NAMES = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'cache_write_tokens', 'cache_creation_input_tokens', 'reasoning_tokens', 'input_tokens_details.cached_tokens', 'input_tokens_details.cache_read_tokens', 'input_tokens_details.cache_write_tokens', 'input_tokens_details.cache_creation_tokens', 'input_tokens_details.cache_creation_input_tokens', 'output_tokens_details.reasoning_tokens'];
@@ -661,6 +662,10 @@ export const executeCodex = async params => {
     }
   }
 
+  // Issue #1877: deploy the experimental HANDOFF.md Agent Skill so Codex loads
+  // it natively from .agents/skills/handoff/SKILL.md (no-op unless --use-handoff).
+  await deployHandoffSkill({ tempDir, argv, log, $ });
+
   // Execute the Codex command
   return await executeCodexCommand({
     tempDir,

package/src/codex.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getHandoffSubPrompt } from './handoff.prompts.lib.mjs';
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
@@ -306,7 +307,7 @@ Visual UI work and screenshots.
    - When the fix is visual, include side-by-side or sequential comparison of before/after states in the PR description.
    - When possible, create automated visual regression tests to prevent the UI bug from recurring.`
        : ''
-   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${buildWorkLanguageDirective()}`;
+   }${ciExamples}${getArchitectureCareSubPrompt(argv)}${getHandoffSubPrompt(argv)}${buildWorkLanguageDirective()}`;
 };
 
 // Export all functions as default object too

package/src/handoff-skill.lib.mjs

@@ -0,0 +1,256 @@
+/**
+ * HANDOFF.md Agent Skill deployment (issue #1877)
+ *
+ * Writes the canonical handoff `SKILL.md` (built by handoff.prompts.lib.mjs)
+ * into the session working directory so the AI tool loads it natively as an
+ * Agent Skill, instead of relying on an injected prompt.
+ *
+ * Both supported tools read the Agent Skills standard, but from different
+ * hardcoded project directories (neither tool exposes a setting or env var to
+ * point at a custom/shared folder):
+ *   - Claude Code:  .claude/skills/<name>/SKILL.md
+ *   - Codex:        .agents/skills/<name>/SKILL.md
+ *
+ * To answer "can both CLIs use the SAME folder?": there is no native shared
+ * location, so we make one ourselves. The SKILL.md is written exactly ONCE into
+ * a single real directory (the Claude path, `.claude/skills/handoff/`), and the
+ * Codex path (`.agents/skills/handoff`) is a relative **symlink** pointing at
+ * that one real directory. Both tools therefore read byte-for-byte the same
+ * file from a single source of truth on disk — not two copies that could drift.
+ * If the filesystem cannot create a symlink (e.g. Windows without privilege),
+ * we fall back to writing a real second copy so the feature still works.
+ *
+ * The deployed skill is tool configuration, not project state, so it is:
+ *   - re-deployed every session by hive-mind (each session clones fresh), and
+ *   - excluded from git via `.git/info/exclude` (a local, never-committed
+ *     ignore) so it never pollutes the pull request or the "uncommitted
+ *     changes" checks. Only the HANDOFF.md the tool produces is committed.
+ */
+
+// Fetch use-m if not available (matches the rest of src/*.lib.mjs).
+if (typeof globalThis.use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+const fs = (await use('fs')).promises;
+const path = (await use('path')).default;
+
+import { buildHandoffSkillFile, HANDOFF_SKILL_NAME } from './handoff.prompts.lib.mjs';
+
+const noopLog = async () => {};
+
+const SKILL_FILE = 'SKILL.md';
+
+/**
+ * The single real skill directory the SKILL.md is written into. Claude Code
+ * reads it directly; Codex reaches the same files through a symlink (below).
+ * @type {string}
+ */
+export const HANDOFF_PRIMARY_SKILL_DIR = path.join('.claude', 'skills', HANDOFF_SKILL_NAME);
+
+/**
+ * Additional skill directories that should resolve to the same SKILL.md. Each
+ * is created as a symlink to HANDOFF_PRIMARY_SKILL_DIR (one source of truth),
+ * falling back to a real copy only if symlinking is unsupported.
+ * @type {string[]}
+ */
+export const HANDOFF_LINKED_SKILL_DIRS = Object.freeze([
+  path.join('.agents', 'skills', HANDOFF_SKILL_NAME), // Codex
+]);
+
+/**
+ * All skill directories the deployment touches (primary + links). Kept for the
+ * git-exclude bookkeeping and for callers/tests that enumerate every location.
+ * @type {string[]}
+ */
+export const HANDOFF_SKILL_DIRS = Object.freeze([HANDOFF_PRIMARY_SKILL_DIR, ...HANDOFF_LINKED_SKILL_DIRS]);
+
+/**
+ * Determine whether a path is already tracked by git in the working dir. We
+ * never clobber a file/dir the target repository tracks itself.
+ */
+const isTracked = async ({ $, tempDir, relPath }) => {
+  if (!$) return false;
+  try {
+    const result = await $({ cwd: tempDir })`git ls-files --error-unmatch ${relPath} 2>/dev/null`;
+    return result.code === 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Resolve the local git exclude file (`.git/info/exclude`), honoring worktrees
+ * via `git rev-parse --git-path`. Falls back to the conventional location.
+ */
+const resolveExcludePath = async ({ $, tempDir }) => {
+  if ($) {
+    try {
+      const result = await $({ cwd: tempDir })`git rev-parse --git-path info/exclude 2>/dev/null`;
+      const rel = (result.stdout || '').toString().trim();
+      if (result.code === 0 && rel) {
+        return path.isAbsolute(rel) ? rel : path.join(tempDir, rel);
+      }
+    } catch {
+      // fall through to default
+    }
+  }
+  return path.join(tempDir, '.git', 'info', 'exclude');
+};
+
+/**
+ * Append the skill directories to `.git/info/exclude` (idempotent) so the
+ * deployed SKILL.md files (real dir and symlink alike) stay invisible to git.
+ * Entries are written WITHOUT a trailing slash so they match both a real
+ * directory and a directory symlink (git would not match a symlink against a
+ * `dir/` pattern).
+ */
+const updateGitExclude = async ({ $, tempDir, log }) => {
+  const excludePath = await resolveExcludePath({ $, tempDir });
+  // Only touch the exclude file if its parent (.git/info) exists — i.e. this is
+  // a real git working dir. Avoid creating a stray `.git/` in non-git dirs.
+  try {
+    await fs.access(path.dirname(excludePath));
+  } catch {
+    await log('   Handoff skill: no .git/info directory; skipping git-exclude update', { verbose: true });
+    return false;
+  }
+
+  let existing = '';
+  try {
+    existing = await fs.readFile(excludePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const entries = HANDOFF_SKILL_DIRS.map(dir => `/${dir.split(path.sep).join('/')}`);
+  const existingLines = existing.split(/\r?\n/);
+  const missing = entries.filter(entry => !existingLines.includes(entry));
+  if (missing.length === 0) return true;
+
+  const header = '# hive-mind --use-handoff: experimental HANDOFF.md Agent Skill (issue #1877)';
+  const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  const block = `${prefix}${existing.includes(header) ? '' : header + '\n'}${missing.join('\n')}\n`;
+  await fs.writeFile(excludePath, existing + block, 'utf8');
+  return true;
+};
+
+/**
+ * Write the real SKILL.md into the primary skill directory.
+ */
+const writeRealSkill = async ({ tempDir, content }) => {
+  const absDir = path.join(tempDir, HANDOFF_PRIMARY_SKILL_DIR);
+  await fs.mkdir(absDir, { recursive: true });
+  await fs.writeFile(path.join(absDir, SKILL_FILE), content, 'utf8');
+  return absDir;
+};
+
+/**
+ * Make `relLinkDir` resolve to the same files as the primary skill directory.
+ * Prefers a relative symlink (single source of truth); if symlinking is not
+ * supported, falls back to writing a real copy of the SKILL.md.
+ *
+ * @returns {Promise<'symlink'|'copy'>}
+ */
+const linkOrCopySkill = async ({ tempDir, relLinkDir, primaryAbsDir, content }) => {
+  const absLinkDir = path.join(tempDir, relLinkDir);
+  const parent = path.dirname(absLinkDir);
+  await fs.mkdir(parent, { recursive: true });
+  const relTarget = path.relative(parent, primaryAbsDir);
+
+  // Reconcile any pre-existing entry (e.g. from a prior session re-deploy).
+  try {
+    const st = await fs.lstat(absLinkDir);
+    if (st.isSymbolicLink()) {
+      const current = await fs.readlink(absLinkDir);
+      if (current === relTarget) return 'symlink'; // already correct
+      await fs.rm(absLinkDir, { recursive: true, force: true });
+    } else if (st.isDirectory()) {
+      // A real directory is already there (prior copy fallback). Refresh the
+      // copy in place rather than replacing the directory.
+      await fs.writeFile(path.join(absLinkDir, SKILL_FILE), content, 'utf8');
+      return 'copy';
+    } else {
+      await fs.rm(absLinkDir, { force: true });
+    }
+  } catch {
+    // Nothing there yet — fall through and create it.
+  }
+
+  try {
+    await fs.symlink(relTarget, absLinkDir, 'dir');
+    return 'symlink';
+  } catch {
+    await fs.mkdir(absLinkDir, { recursive: true });
+    await fs.writeFile(path.join(absLinkDir, SKILL_FILE), content, 'utf8');
+    return 'copy';
+  }
+};
+
+/**
+ * Deploy the handoff SKILL.md into the session working directory.
+ *
+ * @param {Object} params
+ * @param {string} params.tempDir - The repo working directory.
+ * @param {Object} params.argv - Parsed CLI args (uses argv.useHandoff).
+ * @param {Function} [params.log] - Logger.
+ * @param {Function} [params.$] - Command runner (for git checks); optional.
+ * @returns {Promise<{deployed: boolean, reason?: string, paths: string[], shared: boolean}>}
+ */
+export const deployHandoffSkill = async ({ tempDir, argv, log = noopLog, $ = null } = {}) => {
+  if (!argv || !argv.useHandoff) {
+    return { deployed: false, reason: 'disabled', paths: [], shared: false };
+  }
+  if (!tempDir) {
+    return { deployed: false, reason: 'no-temp-dir', paths: [], shared: false };
+  }
+
+  const content = buildHandoffSkillFile();
+  const written = [];
+  let allShared = true;
+
+  // 1. Write the single real SKILL.md (unless the repo tracks it itself).
+  const primaryRelFile = path.join(HANDOFF_PRIMARY_SKILL_DIR, SKILL_FILE);
+  let primaryAbsDir = path.join(tempDir, HANDOFF_PRIMARY_SKILL_DIR);
+  if (await isTracked({ $, tempDir, relPath: primaryRelFile })) {
+    await log(`   Handoff skill: ${primaryRelFile} is tracked by the repo; leaving it untouched`, { verbose: true });
+  } else {
+    try {
+      primaryAbsDir = await writeRealSkill({ tempDir, content });
+      written.push(primaryRelFile);
+    } catch (error) {
+      await log(`   Handoff skill: failed to deploy ${primaryRelFile}: ${error.message}`, { verbose: true });
+      return { deployed: false, reason: 'write-failed', paths: [], shared: false };
+    }
+  }
+
+  // 2. Point every other tool's skill dir at that same real directory.
+  for (const relLinkDir of HANDOFF_LINKED_SKILL_DIRS) {
+    const relFile = path.join(relLinkDir, SKILL_FILE);
+    if (await isTracked({ $, tempDir, relPath: relFile })) {
+      await log(`   Handoff skill: ${relFile} is tracked by the repo; leaving it untouched`, { verbose: true });
+      continue;
+    }
+    try {
+      const mode = await linkOrCopySkill({ tempDir, relLinkDir, primaryAbsDir, content });
+      if (mode !== 'symlink') allShared = false;
+      written.push(relFile);
+    } catch (error) {
+      await log(`   Handoff skill: failed to link ${relFile}: ${error.message}`, { verbose: true });
+    }
+  }
+
+  if (written.length > 0) {
+    await updateGitExclude({ $, tempDir, log });
+    const how = allShared ? 'one shared folder via symlink' : 'copied (symlink unsupported)';
+    await log(`   Handoff skill deployed (--use-handoff, ${how}): ${written.join(', ')}`, { verbose: true });
+  }
+
+  return { deployed: written.length > 0, paths: written, shared: allShared };
+};
+
+export default {
+  HANDOFF_PRIMARY_SKILL_DIR,
+  HANDOFF_LINKED_SKILL_DIRS,
+  HANDOFF_SKILL_DIRS,
+  deployHandoffSkill,
+};

package/src/handoff.prompts.lib.mjs

@@ -0,0 +1,158 @@
+/**
+ * HANDOFF.md support — Agent Skill (issue #1877)
+ *
+ * Instead of injecting a bespoke sub-prompt, this module ships a real
+ * **Agent Skill** (https://agentskills.io) — a `SKILL.md` document with YAML
+ * frontmatter — that teaches the AI tool to read and maintain a HANDOFF.md file
+ * in the repository root. The Agent Skills format is an open standard (created
+ * by Anthropic) that BOTH supported tools load natively:
+ *   - Claude Code discovers project skills from `.claude/skills/<name>/SKILL.md`.
+ *   - Codex discovers project skills from `.agents/skills/<name>/SKILL.md`.
+ * The exact same `SKILL.md` works for both, so "same skill, same way" is
+ * satisfied by a single canonical file rather than a tool-specific prompt.
+ * Because neither tool lets you redirect its skills folder, the deployment
+ * writes that file ONCE and symlinks the second tool's path to it, so both
+ * tools literally read the same folder (see handoff-skill.lib.mjs).
+ *
+ * The skill is deployed into the session working directory by
+ * `handoff-skill.lib.mjs` (gated behind the experimental --use-handoff flag).
+ * This module only builds the canonical text; the deployment module writes it.
+ *
+ * Goal: cross-session AND cross-tool continuity — a session driven by one tool
+ * (e.g. Claude) can be continued by another tool (e.g. Codex) inside the same
+ * pull request, because the HANDOFF.md state travels with the branch.
+ *
+ * Design rationale specific to hive-mind:
+ *   - Each working session runs in an ephemeral temp working directory that is
+ *     cloned fresh from the pull request branch. The ONLY state that persists
+ *     between sessions (and between different tools) is what is committed to the
+ *     branch. Therefore, unlike the general "disposable temp-dir handoff"
+ *     convention, the handoff file here MUST be committed to the PR branch so
+ *     the next session/tool can read it. We keep a single active HANDOFF.md per
+ *     branch to avoid ambiguity.
+ *   - The skill file itself (SKILL.md) is tool configuration, not project state,
+ *     so it is re-deployed each session by hive-mind and is NOT committed to the
+ *     target repository (see handoff-skill.lib.mjs).
+ */
+
+/**
+ * The default handoff file name (repository root, relative path).
+ * @type {string}
+ */
+export const HANDOFF_FILE_NAME = 'HANDOFF.md';
+
+/**
+ * The skill directory / invocation name (Agent Skills standard).
+ * @type {string}
+ */
+export const HANDOFF_SKILL_NAME = 'handoff';
+
+/**
+ * The skill description used in the SKILL.md frontmatter. Front-loads the key
+ * use case and trigger words so the tool can match the skill implicitly.
+ * @type {string}
+ */
+export const HANDOFF_SKILL_DESCRIPTION = "Maintain a HANDOFF.md continuity document in the repository root so any session can continue a previous session's work — even across different AI tools (Claude and Codex) in the same pull request. Use when starting, resuming, or finishing work on a long-running task, issue, or pull request.";
+
+/**
+ * Build the canonical handoff skill instructions (the markdown body that follows
+ * the YAML frontmatter in SKILL.md). This is tool-agnostic and identical for
+ * Claude and Codex.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @returns {string} The markdown instructions body.
+ */
+export const buildHandoffSkillBody = ({ fileName = HANDOFF_FILE_NAME } = {}) => {
+  return `# HANDOFF.md continuity skill
+
+${fileName} is a single shared handoff document in the repository root that lets any session continue the work of any previous session, even when a different AI tool (for example Claude and Codex) is used. It travels with the pull request branch, so it is the cross-tool, cross-session memory for this PR.
+
+## When to use this skill
+
+- When you start a working session, read ${fileName} first if it exists. Treat its "Next steps" section as your immediate starting point and honor the decisions and constraints it records before exploring anything else.
+- When ${fileName} does not exist yet and the task is non-trivial, create it early so an interrupted session can always be resumed.
+- When you make meaningful progress, update ${fileName} so it always reflects the current truth. Keep exactly one active ${fileName} per pull request branch (do not create per-session copies).
+- When all requirements are fully met and the work is complete, record that completion at the top of ${fileName} (or delete the file) so the next session knows there is nothing left to continue.
+
+## How to write ${fileName}
+
+- Keep it concise and tool-agnostic: describe state by referencing file paths, function names, branch, and commit SHAs rather than tool-specific commands, so the next tool (Claude or Codex) can act on it directly. Prefer pointers to existing artifacts over duplicating their content.
+- Include these sections:
+  1. **Task** — the issue/PR being solved and the goal.
+  2. **Current state** — what is done and verified.
+  3. **Decisions** — key choices made and why (so they are not re-litigated).
+  4. **Next steps** — the concrete, ordered actions the next session should take.
+  5. **Gotchas** — known pitfalls, failing checks, or constraints.
+  6. **Critical files** — the important paths and what each is for.
+- When you record next steps, make them specific and actionable (a path, a function, a command to run) instead of vague goals, and remove items as they are completed.
+
+## Committing and safety
+
+- When you finish a step that changes the state, commit ${fileName} together with the related code changes so the handoff stays in sync with the branch and is never lost if the session is interrupted.
+- Never include secrets, tokens, API keys, passwords, or personal data in ${fileName} — it is committed to the repository.`;
+};
+
+/**
+ * Build a complete SKILL.md document (Agent Skills standard): YAML frontmatter
+ * with `name` and `description`, followed by the instructions body. This exact
+ * file is deployed verbatim for both Claude (.claude/skills/handoff/SKILL.md)
+ * and Codex (.agents/skills/handoff/SKILL.md).
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @param {string} [options.name=HANDOFF_SKILL_NAME] - Skill name (frontmatter).
+ * @param {string} [options.description=HANDOFF_SKILL_DESCRIPTION] - Skill description.
+ * @returns {string} The full SKILL.md content.
+ */
+export const buildHandoffSkillFile = ({ fileName = HANDOFF_FILE_NAME, name = HANDOFF_SKILL_NAME, description = HANDOFF_SKILL_DESCRIPTION } = {}) => {
+  return `---
+name: ${name}
+description: ${description}
+---
+
+${buildHandoffSkillBody({ fileName })}
+`;
+};
+
+/**
+ * Build a minimal activation nudge for the system prompt. The full procedure
+ * lives in the deployed SKILL.md (loaded natively by the tool); this short
+ * pointer only ensures the read-at-session-start behavior reliably fires, since
+ * that is triggered by session lifecycle rather than by a task description.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.fileName=HANDOFF_FILE_NAME] - Handoff file name.
+ * @param {string} [options.name=HANDOFF_SKILL_NAME] - Skill name.
+ * @returns {string} The activation nudge.
+ */
+export const buildHandoffSubPrompt = ({ fileName = HANDOFF_FILE_NAME, name = HANDOFF_SKILL_NAME } = {}) => {
+  return `
+HANDOFF.md continuity skill (experimental, --use-handoff).
+   - A reusable "${name}" Agent Skill is installed in this workspace (.claude/skills/${name}/ for Claude, .agents/skills/${name}/ for Codex). It defines how to read and maintain ${fileName} so any session can continue the work of a previous one — even across tools (Claude and Codex) in the same pull request.
+   - At the start of this session, use the ${name} skill: if ${fileName} exists in the repository root, read it first and continue from its "Next steps". Create or update ${fileName} as you make progress and commit it to the pull request branch.`;
+};
+
+/**
+ * Get the handoff skill activation nudge if enabled.
+ *
+ * @param {Object} argv - Parsed command line arguments.
+ * @returns {string} The sub-prompt content, or an empty string when disabled.
+ */
+export const getHandoffSubPrompt = argv => {
+  if (argv && argv.useHandoff) {
+    return buildHandoffSubPrompt();
+  }
+  return '';
+};
+
+// Export all functions as default object too (mirrors architecture-care module)
+export default {
+  HANDOFF_FILE_NAME,
+  HANDOFF_SKILL_NAME,
+  HANDOFF_SKILL_DESCRIPTION,
+  buildHandoffSkillBody,
+  buildHandoffSkillFile,
+  buildHandoffSubPrompt,
+  getHandoffSubPrompt,
+};

package/src/isolation-runner.lib.mjs

@@ -28,8 +28,13 @@ const { $ } = await use('command-stream');
 const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
 const RUNNING_SESSION_STATUSES = new Set(['executing', 'running']);
 const TERMINAL_SESSION_STATUSES = new Set(['executed', 'completed', 'failed', 'cancelled', 'canceled', 'error']);
-const DEFAULT_HIVE_MIND_IMAGE = 'konard/hive-mind:latest';
-const DEFAULT_HIVE_MIND_DIND_IMAGE = 'konard/hive-mind-dind:latest';
+const HIVE_MIND_IMAGE_REPO = 'konard/hive-mind';
+const HIVE_MIND_DIND_IMAGE_REPO = 'konard/hive-mind-dind';
+const DEFAULT_HIVE_MIND_IMAGE_TAG = 'latest';
+// Docker's `--pull` accepts these policies. We only emit the flag when an
+// operator explicitly opts in; otherwise Docker's own default ("missing")
+// applies and `docker run` reuses any locally present image. See issue #1879.
+const VALID_DOCKER_PULL_POLICIES = new Set(['always', 'missing', 'never']);
 const DOCKER_ISOLATION_TRACKING_BACKEND = 'screen';
 const DOCKER_CONTAINER_HOME = '/home/box';
 const DOCKER_CONTAINER_PREFIX = 'hive-mind-isolation';
@@ -79,15 +84,52 @@ function maybeAddMount(mounts, source, target, existsSync) {
   mounts.push({ source, target });
 }
 
+/**
+ * Resolve the tag used for the Docker isolation image.
+ *
+ * Defaults to `latest`, but operators can pin it (e.g. to the exact version
+ * already present on the host) via `HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG`.
+ * Pinning matters for Docker-in-Docker deployments: the nested daemon starts
+ * with an empty image store, so an unpinned `:latest` whose registry digest has
+ * drifted from the host copy forces a fresh multi-gigabyte pull on every task.
+ * A pinned tag lets a pre-seeded image be reused instead. See issue #1879.
+ */
+export function resolveDockerIsolationImageTag({ env = process.env } = {}) {
+  const explicit = String(env.HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG || '').trim();
+  return explicit || DEFAULT_HIVE_MIND_IMAGE_TAG;
+}
+
 /**
  * Pick the Docker image used for `--isolation docker`.
  *
  * start-command defaults its Docker backend to a base OS image. Hive Mind needs
  * an image with the same CLI/tooling baseline as the parent process instead.
+ *
+ * `HIVE_MIND_DOCKER_ISOLATION_IMAGE` is a full override (repo:tag). Otherwise
+ * the repo is chosen by image variant and the tag by
+ * `resolveDockerIsolationImageTag()`.
  */
 export function getDockerIsolationImage({ env = process.env } = {}) {
   if (env.HIVE_MIND_DOCKER_ISOLATION_IMAGE) return env.HIVE_MIND_DOCKER_ISOLATION_IMAGE;
-  return String(env.HIVE_MIND_IMAGE_VARIANT || '').toLowerCase() === 'dind' ? DEFAULT_HIVE_MIND_DIND_IMAGE : DEFAULT_HIVE_MIND_IMAGE;
+  const repo = String(env.HIVE_MIND_IMAGE_VARIANT || '').toLowerCase() === 'dind' ? HIVE_MIND_DIND_IMAGE_REPO : HIVE_MIND_IMAGE_REPO;
+  return `${repo}:${resolveDockerIsolationImageTag({ env })}`;
+}
+
+/**
+ * Resolve the Docker `--pull` policy for isolated tasks.
+ *
+ * Returns one of `always` | `missing` | `never`, or `null` when unset (in which
+ * case the `--pull` flag is omitted and Docker's default applies). Operators set
+ * `HIVE_MIND_DOCKER_ISOLATION_PULL=never` to force reuse of an image already
+ * present in the (possibly nested) daemon and fail fast instead of silently
+ * re-downloading it. Invalid values are ignored. See issue #1879.
+ */
+export function getDockerIsolationPullPolicy({ env = process.env } = {}) {
+  const raw = String(env.HIVE_MIND_DOCKER_ISOLATION_PULL || '')
+    .trim()
+    .toLowerCase();
+  if (!raw) return null;
+  return VALID_DOCKER_PULL_POLICIES.has(raw) ? raw : null;
 }
 
 /**
@@ -123,7 +165,16 @@ export function buildDockerIsolationCommand(command, args = [], options = {}) {
   const { sessionId, tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync } = options;
   const image = getDockerIsolationImage({ env });
   const innerCommand = buildShellCommand(command, args);
-  const dockerArgs = ['docker', 'run', '--rm', '--name', makeDockerContainerName(sessionId), '--workdir', DOCKER_CONTAINER_HOME, '-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`];
+  const dockerArgs = ['docker', 'run', '--rm'];
+
+  // Reuse a locally present image instead of re-downloading it when the
+  // operator opts in. Omitted by default so Docker's "missing" policy applies.
+  const pullPolicy = getDockerIsolationPullPolicy({ env });
+  if (pullPolicy) {
+    dockerArgs.push('--pull', pullPolicy);
+  }
+
+  dockerArgs.push('--name', makeDockerContainerName(sessionId), '--workdir', DOCKER_CONTAINER_HOME, '-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`);
 
   if (shouldRunPrivilegedDockerIsolation(image, env)) {
     dockerArgs.push('--privileged');
@@ -359,9 +410,12 @@ export async function executeWithIsolation(command, args, options = {}) {
   if (verbose) {
     console.log(`[VERBOSE] isolation-runner: ${[binPath, ...startCommandArgs].map(shellQuote).join(' ')}`);
     if (backend === 'docker') {
-      const image = getDockerIsolationImage({ env: options.env || process.env });
-      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env: options.env || process.env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
+      const env = options.env || process.env;
+      const image = getDockerIsolationImage({ env });
+      const pullPolicy = getDockerIsolationPullPolicy({ env });
+      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
       console.log(`[VERBOSE] isolation-runner: Docker isolation image: ${image}`);
+      console.log(`[VERBOSE] isolation-runner: Docker isolation pull policy: ${pullPolicy || '(docker default: missing — reuse local image if present)'}`);
       console.log(`[VERBOSE] isolation-runner: Docker isolation mounts: ${mounts.map(m => m.target).join(', ') || '(none)'}`);
     }
   }

package/src/option-suggestions.lib.mjs

@@ -189,6 +189,7 @@ const KNOWN_OPTION_NAMES = [
   'prompt-issue-reporting',
   'prompt-architecture-care',
   'prompt-case-studies',
+  'use-handoff',
   'prompt-playwright-mcp',
   'prompt-check-sibling-pull-requests',
   'enable-workspaces',

package/src/solve.branch-divergence.lib.mjs

@@ -38,6 +38,61 @@ export function classifyPushRejection(errorOutput = '') {
   return 'unknown';
 }
 
+/**
+ * Detect whether a push failure was caused by missing permissions rather than
+ * by branch divergence. Git surfaces this as `! [remote rejected] ...
+ * (permission denied)` (HTTP 403). This is fundamentally different from a
+ * non-fast-forward / divergence rejection: force-pushing or force-with-lease
+ * will NOT help because the user simply cannot write to the remote.
+ *
+ * Issue #1893: when continuing another contributor's fork PR, the maintainer
+ * does not own the fork, so pushing the fork's default branch is rejected with
+ * "permission denied". The old heuristic matched the substring "rejected" and
+ * misclassified this as fork divergence, halting the run and recommending a
+ * useless `--allow-fork-divergence-resolution-using-force-push-with-lease`.
+ */
+export function isPermissionDeniedPushError(errorOutput = '') {
+  const normalized = String(errorOutput || '').toLowerCase();
+  return normalized.includes('permission denied') || normalized.includes('permission to') || normalized.includes('error: 403') || normalized.includes('the requested url returned error: 403') || (normalized.includes('denied') && normalized.includes('to https://'));
+}
+
+/**
+ * Decide whether the solver should push the freshly-synced default branch to
+ * the fork's `origin` remote.
+ *
+ * We only push the default branch to keep a fork we OWN in sync with upstream.
+ * When continuing someone else's fork PR (the fork belongs to the contributor,
+ * not the current user), the maintainer has push rights only to the PR branch
+ * (via "Allow edits by maintainers"), never to the fork's default branch.
+ * Attempting the push is both impossible (permission denied) and unnecessary,
+ * so we skip it. Issue #1893.
+ *
+ * @param {object} params
+ * @param {string|null} params.currentUser - authenticated GitHub login
+ * @param {string|null} params.forkedRepo - "owner/name" of the fork (origin)
+ * @returns {{ shouldPush: boolean, reason: string, forkOwner: string|null }}
+ */
+export function shouldPushDefaultBranchToFork({ currentUser, forkedRepo } = {}) {
+  const forkOwner = forkedRepo && forkedRepo.includes('/') ? forkedRepo.split('/')[0] : null;
+
+  if (!forkOwner) {
+    // Without a parseable fork owner we cannot prove ownership; fall back to the
+    // historical behaviour of attempting the push so nothing regresses.
+    return { shouldPush: true, reason: 'fork-owner-unknown', forkOwner: null };
+  }
+
+  if (!currentUser) {
+    // Could not resolve the current user; attempt the push and let git report.
+    return { shouldPush: true, reason: 'current-user-unknown', forkOwner };
+  }
+
+  if (currentUser.toLowerCase() === forkOwner.toLowerCase()) {
+    return { shouldPush: true, reason: 'owns-fork', forkOwner };
+  }
+
+  return { shouldPush: false, reason: 'not-fork-owner', forkOwner };
+}
+
 export function shouldTreatPushRejectionAsRemoteSynchronized(divergence = null) {
   if (!divergence?.remoteExists || divergence.ahead !== 0 || divergence.behind !== 0) {
     return false;

package/src/solve.config.lib.mjs

@@ -480,6 +480,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Supported for --tool claude and --tool codex.',
     default: false,
   },
+  'use-handoff': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Enable the HANDOFF.md continuity Agent Skill so a session can continue the work of a previous session — even when a different AI tool is used (e.g. Claude and Codex continuing each other in the same pull request). A real SKILL.md (the open Agent Skills standard) is deployed into the working directory so each tool loads it natively (.claude/skills/handoff/ for Claude, .agents/skills/handoff/ for Codex). The AI reads HANDOFF.md (repository root) first when present and keeps it updated with task, current state, decisions, next steps, gotchas, and critical files. HANDOFF.md is committed to the PR branch so it persists across the ephemeral per-session working directories; the SKILL.md itself is re-deployed each session and git-excluded so it never pollutes the PR. The same skill file is used identically for --tool claude and --tool codex. Disabled by default (issue #1877).',
+    default: false,
+  },
   'prompt-playwright-mcp': {
     type: 'boolean',
     description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Supported for --tool claude, --tool codex, --tool opencode, --tool agent, --tool qwen, and --tool gemini.',

package/src/solve.fork-sync.lib.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+// Fork upstream-sync module for the solve command.
+// Extracted from solve.repository.lib.mjs to keep files under 1500 lines (#1893).
+
+// Use use-m to dynamically import modules for cross-runtime compatibility
+// Check if use is already defined globally (when imported from solve.mjs)
+// If not, fetch it (when running standalone)
+if (typeof globalThis.use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+const use = globalThis.use;
+
+// Use command-stream for consistent $ behavior; wrap with rate-limit retry (#1726)
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry((await use('command-stream')).$);
+
+// Import shared library functions
+const lib = await import('./lib.mjs');
+const { log, formatAligned } = lib;
+
+// Import exit handler
+import { safeExit } from './exit-handler.lib.mjs';
+
+// Issue #1893: helpers that decide whether the fork's default branch may be
+// pushed and that distinguish a permission-denied rejection from a genuine
+// fork divergence.
+const { isPermissionDeniedPushError, shouldPushDefaultBranchToFork } = await import('./solve.branch-divergence.lib.mjs');
+
+// Set up upstream remote and sync fork
+export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote, owner, repo, argv) => {
+  if (!forkedRepo || !upstreamRemote) return;
+
+  await log(`${formatAligned('🔗', 'Setting upstream:', upstreamRemote)}`);
+
+  // Check if upstream remote already exists
+  const checkUpstreamResult = await $({ cwd: tempDir })`git remote get-url upstream 2>/dev/null`;
+  let upstreamExists = checkUpstreamResult.code === 0;
+
+  if (upstreamExists) {
+    await log(`${formatAligned('ℹ️', 'Upstream exists:', 'Using existing upstream remote')}`);
+  } else {
+    // Add upstream remote since it doesn't exist
+    const upstreamResult = await $({ cwd: tempDir })`git remote add upstream https://github.com/${upstreamRemote}.git`;
+
+    if (upstreamResult.code === 0) {
+      await log(`${formatAligned('✅', 'Upstream set:', upstreamRemote)}`);
+      upstreamExists = true;
+    } else {
+      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to add upstream remote')}`);
+      if (upstreamResult.stderr) {
+        await log(`${formatAligned('', 'Error details:', upstreamResult.stderr.toString().trim())}`);
+      }
+    }
+  }
+
+  // Proceed with fork sync if upstream remote is available
+  if (upstreamExists) {
+    // Fetch upstream
+    await log(`${formatAligned('🔄', 'Fetching upstream...', '')}`);
+    const fetchResult = await $({ cwd: tempDir })`git fetch upstream`;
+    if (fetchResult.code === 0) {
+      await log(`${formatAligned('✅', 'Upstream fetched:', 'Successfully')}`);
+
+      // Sync the default branch with upstream to avoid merge conflicts
+      await log(`${formatAligned('🔄', 'Syncing default branch...', '')}`);
+
+      // Get current branch so we can return to it after sync
+      const currentBranchResult = await $({ cwd: tempDir })`git branch --show-current`;
+      if (currentBranchResult.code === 0) {
+        const currentBranch = currentBranchResult.stdout.toString().trim();
+
+        // Get the default branch name from the original repository using GitHub API
+        const repoInfoResult = await $`gh api repos/${owner}/${repo} --jq .default_branch`;
+        if (repoInfoResult.code === 0) {
+          const upstreamDefaultBranch = repoInfoResult.stdout.toString().trim();
+          await log(`${formatAligned('ℹ️', 'Default branch:', upstreamDefaultBranch)}`);
+
+          // Always sync the default branch, regardless of current branch
+          // This ensures fork is up-to-date even if we're working on a different branch
+
+          // Step 1: Switch to default branch if not already on it
+          let syncSuccessful = true;
+          if (currentBranch !== upstreamDefaultBranch) {
+            await log(`${formatAligned('🔄', 'Switching to:', `${upstreamDefaultBranch} branch`)}`);
+            const checkoutResult = await $({ cwd: tempDir })`git checkout ${upstreamDefaultBranch}`;
+            if (checkoutResult.code !== 0) {
+              await log(`${formatAligned('⚠️', 'Warning:', `Failed to checkout ${upstreamDefaultBranch}`)}`);
+              syncSuccessful = false; // Cannot proceed with sync
+            }
+          }
+
+          // Step 2: Sync default branch with upstream (only if checkout was successful)
+          if (syncSuccessful) {
+            const syncResult = await $({ cwd: tempDir })`git reset --hard upstream/${upstreamDefaultBranch}`;
+            if (syncResult.code === 0) {
+              await log(`${formatAligned('✅', 'Default branch synced:', `with upstream/${upstreamDefaultBranch}`)}`);
+
+              // Step 3: Push the updated default branch to fork to keep it in sync.
+              //
+              // Issue #1893: only push the default branch when the current user
+              // OWNS the fork. When continuing another contributor's fork PR the
+              // fork belongs to them, and "Allow edits by maintainers" grants
+              // push access only to the PR branch — never to the fork's default
+              // branch. Attempting the push there is guaranteed to be rejected
+              // with "permission denied" and is unnecessary, so we skip it and
+              // keep working on the PR branch.
+              const currentUserResult = await $`gh api user --jq .login`;
+              const currentUser = currentUserResult.code === 0 ? currentUserResult.stdout.toString().trim() : null;
+              const pushDecision = shouldPushDefaultBranchToFork({ currentUser, forkedRepo });
+
+              if (!pushDecision.shouldPush) {
+                await log(`${formatAligned('ℹ️', 'Skipping fork push:', `${upstreamDefaultBranch} synced locally only`)}`);
+                await log(`${formatAligned('', 'Reason:', `Fork ${forkedRepo} is owned by ${pushDecision.forkOwner}, not ${currentUser || 'the current user'}`)}`, {
+                  verbose: true,
+                });
+                await log(`${formatAligned('', 'Next:', 'Continuing on the PR branch (maintainer edits allowed on the PR head only)')}`, {
+                  verbose: true,
+                });
+                // Fall through to Step 4 (return to original branch) without pushing.
+                if (currentBranch !== upstreamDefaultBranch) {
+                  await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                  const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                  if (returnResult.code === 0) {
+                    await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                  } else {
+                    await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                  }
+                }
+                return;
+              }
+
+              await log(`${formatAligned('🔄', 'Pushing to fork:', `${upstreamDefaultBranch} branch`)}`);
+              const pushResult = await $({ cwd: tempDir })`git push origin ${upstreamDefaultBranch} 2>&1`;
+              if (pushResult.code === 0) {
+                await log(`${formatAligned('✅', 'Fork updated:', 'Default branch pushed to fork')}`);
+              } else {
+                // Check if it's a non-fast-forward error (fork has diverged from upstream)
+                const errorMsg = (pushResult.stderr ? pushResult.stderr.toString().trim() : '') || (pushResult.stdout ? pushResult.stdout.toString().trim() : '');
+
+                // Issue #1893: a "permission denied" rejection is NOT a divergence.
+                // It means the current user cannot write to this fork (e.g. it
+                // belongs to another contributor). Force-push / force-with-lease
+                // cannot fix that, so never recommend the divergence flag here.
+                // Syncing the default branch is best-effort, so we warn and
+                // continue working on the PR branch instead of halting.
+                if (isPermissionDeniedPushError(errorMsg)) {
+                  await log('');
+                  await log(`${formatAligned('ℹ️', 'Skipping fork sync:', `No push access to ${forkedRepo}`)}`);
+                  await log(`${formatAligned('', 'Reason:', "Fork's default branch is owned by another user; this is expected when")}`, { verbose: true });
+                  await log(`${formatAligned('', '', "continuing a contributor's fork PR (maintainer edits cover the PR branch only)")}`, { verbose: true });
+                  await log(`${formatAligned('', 'Push output:', errorMsg.split('\n')[0] || errorMsg)}`, { verbose: true });
+                  // Return to the original branch and continue without halting.
+                  if (currentBranch !== upstreamDefaultBranch) {
+                    await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                    const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                    if (returnResult.code === 0) {
+                      await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                    } else {
+                      await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                    }
+                  }
+                  return;
+                }
+
+                const isNonFastForward = errorMsg.includes('non-fast-forward') || errorMsg.includes('rejected') || errorMsg.includes('tip of your current branch is behind');
+
+                if (isNonFastForward) {
+                  // Fork has diverged from upstream
+                  await log('');
+                  await log(`${formatAligned('⚠️', 'FORK DIVERGENCE DETECTED', '')}`, { level: 'warn' });
+                  await log('');
+                  await log('  🔍 What happened:');
+                  await log(`     Your fork's ${upstreamDefaultBranch} branch has different commits than upstream`);
+                  await log('     This typically occurs when upstream had a force push (e.g., git reset --hard)');
+                  await log('');
+                  await log('  📦 Current state:');
+                  await log(`     • Fork: ${forkedRepo}`);
+                  await log(`     • Upstream: ${owner}/${repo}`);
+                  await log(`     • Branch: ${upstreamDefaultBranch}`);
+                  await log('');
+
+                  // Check if user has enabled automatic force push
+                  if (argv.allowForkDivergenceResolutionUsingForcePushWithLease) {
+                    await log('  🔄 Auto-resolution ENABLED (--allow-fork-divergence-resolution-using-force-push-with-lease):');
+                    await log('     Attempting to force-push with --force-with-lease...');
+                    await log('');
+
+                    // Use --force-with-lease for safer force push
+                    // This will only force push if the remote hasn't changed since our last fetch
+                    await log(`${formatAligned('🔄', 'Force pushing:', 'Syncing fork with upstream (--force-with-lease)')}`);
+                    const forcePushResult = await $({
+                      cwd: tempDir,
+                    })`git push --force-with-lease origin ${upstreamDefaultBranch} 2>&1`;
+
+                    if (forcePushResult.code === 0) {
+                      await log(`${formatAligned('✅', 'Fork synced:', 'Successfully force-pushed to align with upstream')}`);
+                      await log('');
+                    } else {
+                      // Force push also failed - this is a more serious issue
+                      await log('');
+                      await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to sync fork with upstream')}`, {
+                        level: 'error',
+                      });
+                      await log('');
+                      await log('  🔍 What happened:');
+                      await log(`     Fork branch ${upstreamDefaultBranch} has diverged from upstream`);
+                      await log('     Both normal push and force-with-lease push failed');
+                      await log('');
+                      await log('  📦 Error details:');
+                      const forceErrorMsg = forcePushResult.stderr ? forcePushResult.stderr.toString().trim() : '';
+                      for (const line of forceErrorMsg.split('\n')) {
+                        if (line.trim()) await log(`     ${line}`);
+                      }
+                      await log('');
+                      await log('  💡 Possible causes:');
+                      await log('     • Fork branch is protected (branch protection rules prevent force push)');
+                      await log('     • Someone else pushed to fork after our fetch');
+                      await log('     • Insufficient permissions to force push');
+                      await log('');
+                      await log('  🔧 Manual resolution:');
+                      await log(`     1. Visit your fork: https://github.com/${forkedRepo}`);
+                      await log('     2. Check branch protection settings');
+                      await log('     3. Manually sync fork with upstream:');
+                      await log('        git fetch upstream');
+                      await log(`        git reset --hard upstream/${upstreamDefaultBranch}`);
+                      await log(`        git push --force origin ${upstreamDefaultBranch}`);
+                      await log('');
+                      await safeExit(1, 'Repository setup failed - fork sync failed');
+                    }
+                  } else {
+                    // Flag is not enabled - provide guidance
+                    await log('  💡 Your options:');
+                    await log('');
+                    await log('     Option 1: Delete your fork and recreate it (SIMPLEST)');
+                    await log(`              gh repo delete ${forkedRepo}`);
+                    await log('              Then run the solve command again - the fork will be recreated automatically');
+                    await log('              ⚠️  Only use this if your fork has no unique commits you need to preserve');
+                    await log('');
+                    await log('     Option 2: Enable automatic force-push (DANGEROUS)');
+                    await log('              Add --allow-fork-divergence-resolution-using-force-push-with-lease flag to your command');
+                    await log('              This will automatically sync your fork with upstream using force-with-lease');
+                    await log('              ⚠️  Overwrites fork history - any unique commits will be LOST');
+                    await log('');
+                    await log('     Option 3: Manually resolve the divergence');
+                    await log('              1. Decide if you need any commits unique to your fork');
+                    await log('              2. If yes, cherry-pick them after syncing');
+                    await log('              3. If no, manually force-push:');
+                    await log('                 git fetch upstream');
+                    await log(`                 git reset --hard upstream/${upstreamDefaultBranch}`);
+                    await log(`                 git push --force origin ${upstreamDefaultBranch}`);
+                    await log('');
+                    await log('  🔧 To proceed with auto-resolution, restart with:');
+                    await log(`     solve ${argv.url || argv['issue-url'] || argv._[0] || '<issue-url>'} --allow-fork-divergence-resolution-using-force-push-with-lease`);
+                    await log('');
+                    await safeExit(1, 'Repository setup halted - fork divergence requires user decision');
+                  }
+                } else {
+                  // Some other push error (not divergence-related)
+                  await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to push updated default branch to fork')}`);
+                  await log(`${formatAligned('', 'Push error:', errorMsg)}`);
+                  await log(`${formatAligned('', 'Reason:', 'Fork must be updated or process must stop')}`);
+                  await log(`${formatAligned('', 'Solution draft:', 'Fork sync is required for proper workflow')}`);
+                  await log(`${formatAligned('', 'Next steps:', '1. Check GitHub permissions for the fork')}`);
+                  await log(`${formatAligned('', '', '2. Ensure fork is not protected')}`);
+                  await log(`${formatAligned('', '', '3. Try again after resolving fork issues')}`);
+                  await safeExit(1, 'Repository setup failed');
+                }
+              }
+
+              // Step 4: Return to the original branch if it was different
+              if (currentBranch !== upstreamDefaultBranch) {
+                await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
+                const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
+                if (returnResult.code === 0) {
+                  await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
+                } else {
+                  await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
+                  // This is not fatal, continue with sync on default branch
+                }
+              }
+            } else {
+              await log(`${formatAligned('⚠️', 'Warning:', `Failed to sync ${upstreamDefaultBranch} with upstream`)}`);
+              if (syncResult.stderr) {
+                await log(`${formatAligned('', 'Sync error:', syncResult.stderr.toString().trim())}`);
+              }
+            }
+          }
+        } else {
+          await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get default branch name')}`);
+        }
+      } else {
+        await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get current branch')}`);
+      }
+    } else {
+      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to fetch upstream')}`);
+      if (fetchResult.stderr) {
+        await log(`${formatAligned('', 'Fetch error:', fetchResult.stderr.toString().trim())}`);
+      }
+    }
+  }
+};

package/src/solve.repository.lib.mjs

@@ -1045,220 +1045,10 @@ export const cloneRepository = async (repoToClone, tempDir, argv, owner, repo) =
   await safeExit(1, 'Repository setup failed');
 };
 
-// Set up upstream remote and sync fork
-export const setupUpstreamAndSync = async (tempDir, forkedRepo, upstreamRemote, owner, repo, argv) => {
-  if (!forkedRepo || !upstreamRemote) return;
-
-  await log(`${formatAligned('🔗', 'Setting upstream:', upstreamRemote)}`);
-
-  // Check if upstream remote already exists
-  const checkUpstreamResult = await $({ cwd: tempDir })`git remote get-url upstream 2>/dev/null`;
-  let upstreamExists = checkUpstreamResult.code === 0;
-
-  if (upstreamExists) {
-    await log(`${formatAligned('ℹ️', 'Upstream exists:', 'Using existing upstream remote')}`);
-  } else {
-    // Add upstream remote since it doesn't exist
-    const upstreamResult = await $({ cwd: tempDir })`git remote add upstream https://github.com/${upstreamRemote}.git`;
-
-    if (upstreamResult.code === 0) {
-      await log(`${formatAligned('✅', 'Upstream set:', upstreamRemote)}`);
-      upstreamExists = true;
-    } else {
-      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to add upstream remote')}`);
-      if (upstreamResult.stderr) {
-        await log(`${formatAligned('', 'Error details:', upstreamResult.stderr.toString().trim())}`);
-      }
-    }
-  }
-
-  // Proceed with fork sync if upstream remote is available
-  if (upstreamExists) {
-    // Fetch upstream
-    await log(`${formatAligned('🔄', 'Fetching upstream...', '')}`);
-    const fetchResult = await $({ cwd: tempDir })`git fetch upstream`;
-    if (fetchResult.code === 0) {
-      await log(`${formatAligned('✅', 'Upstream fetched:', 'Successfully')}`);
-
-      // Sync the default branch with upstream to avoid merge conflicts
-      await log(`${formatAligned('🔄', 'Syncing default branch...', '')}`);
-
-      // Get current branch so we can return to it after sync
-      const currentBranchResult = await $({ cwd: tempDir })`git branch --show-current`;
-      if (currentBranchResult.code === 0) {
-        const currentBranch = currentBranchResult.stdout.toString().trim();
-
-        // Get the default branch name from the original repository using GitHub API
-        const repoInfoResult = await $`gh api repos/${owner}/${repo} --jq .default_branch`;
-        if (repoInfoResult.code === 0) {
-          const upstreamDefaultBranch = repoInfoResult.stdout.toString().trim();
-          await log(`${formatAligned('ℹ️', 'Default branch:', upstreamDefaultBranch)}`);
-
-          // Always sync the default branch, regardless of current branch
-          // This ensures fork is up-to-date even if we're working on a different branch
-
-          // Step 1: Switch to default branch if not already on it
-          let syncSuccessful = true;
-          if (currentBranch !== upstreamDefaultBranch) {
-            await log(`${formatAligned('🔄', 'Switching to:', `${upstreamDefaultBranch} branch`)}`);
-            const checkoutResult = await $({ cwd: tempDir })`git checkout ${upstreamDefaultBranch}`;
-            if (checkoutResult.code !== 0) {
-              await log(`${formatAligned('⚠️', 'Warning:', `Failed to checkout ${upstreamDefaultBranch}`)}`);
-              syncSuccessful = false; // Cannot proceed with sync
-            }
-          }
-
-          // Step 2: Sync default branch with upstream (only if checkout was successful)
-          if (syncSuccessful) {
-            const syncResult = await $({ cwd: tempDir })`git reset --hard upstream/${upstreamDefaultBranch}`;
-            if (syncResult.code === 0) {
-              await log(`${formatAligned('✅', 'Default branch synced:', `with upstream/${upstreamDefaultBranch}`)}`);
-
-              // Step 3: Push the updated default branch to fork to keep it in sync
-              await log(`${formatAligned('🔄', 'Pushing to fork:', `${upstreamDefaultBranch} branch`)}`);
-              const pushResult = await $({ cwd: tempDir })`git push origin ${upstreamDefaultBranch} 2>&1`;
-              if (pushResult.code === 0) {
-                await log(`${formatAligned('✅', 'Fork updated:', 'Default branch pushed to fork')}`);
-              } else {
-                // Check if it's a non-fast-forward error (fork has diverged from upstream)
-                const errorMsg = (pushResult.stderr ? pushResult.stderr.toString().trim() : '') || (pushResult.stdout ? pushResult.stdout.toString().trim() : '');
-                const isNonFastForward = errorMsg.includes('non-fast-forward') || errorMsg.includes('rejected') || errorMsg.includes('tip of your current branch is behind');
-
-                if (isNonFastForward) {
-                  // Fork has diverged from upstream
-                  await log('');
-                  await log(`${formatAligned('⚠️', 'FORK DIVERGENCE DETECTED', '')}`, { level: 'warn' });
-                  await log('');
-                  await log('  🔍 What happened:');
-                  await log(`     Your fork's ${upstreamDefaultBranch} branch has different commits than upstream`);
-                  await log('     This typically occurs when upstream had a force push (e.g., git reset --hard)');
-                  await log('');
-                  await log('  📦 Current state:');
-                  await log(`     • Fork: ${forkedRepo}`);
-                  await log(`     • Upstream: ${owner}/${repo}`);
-                  await log(`     • Branch: ${upstreamDefaultBranch}`);
-                  await log('');
-
-                  // Check if user has enabled automatic force push
-                  if (argv.allowForkDivergenceResolutionUsingForcePushWithLease) {
-                    await log('  🔄 Auto-resolution ENABLED (--allow-fork-divergence-resolution-using-force-push-with-lease):');
-                    await log('     Attempting to force-push with --force-with-lease...');
-                    await log('');
-
-                    // Use --force-with-lease for safer force push
-                    // This will only force push if the remote hasn't changed since our last fetch
-                    await log(`${formatAligned('🔄', 'Force pushing:', 'Syncing fork with upstream (--force-with-lease)')}`);
-                    const forcePushResult = await $({
-                      cwd: tempDir,
-                    })`git push --force-with-lease origin ${upstreamDefaultBranch} 2>&1`;
-
-                    if (forcePushResult.code === 0) {
-                      await log(`${formatAligned('✅', 'Fork synced:', 'Successfully force-pushed to align with upstream')}`);
-                      await log('');
-                    } else {
-                      // Force push also failed - this is a more serious issue
-                      await log('');
-                      await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to sync fork with upstream')}`, {
-                        level: 'error',
-                      });
-                      await log('');
-                      await log('  🔍 What happened:');
-                      await log(`     Fork branch ${upstreamDefaultBranch} has diverged from upstream`);
-                      await log('     Both normal push and force-with-lease push failed');
-                      await log('');
-                      await log('  📦 Error details:');
-                      const forceErrorMsg = forcePushResult.stderr ? forcePushResult.stderr.toString().trim() : '';
-                      for (const line of forceErrorMsg.split('\n')) {
-                        if (line.trim()) await log(`     ${line}`);
-                      }
-                      await log('');
-                      await log('  💡 Possible causes:');
-                      await log('     • Fork branch is protected (branch protection rules prevent force push)');
-                      await log('     • Someone else pushed to fork after our fetch');
-                      await log('     • Insufficient permissions to force push');
-                      await log('');
-                      await log('  🔧 Manual resolution:');
-                      await log(`     1. Visit your fork: https://github.com/${forkedRepo}`);
-                      await log('     2. Check branch protection settings');
-                      await log('     3. Manually sync fork with upstream:');
-                      await log('        git fetch upstream');
-                      await log(`        git reset --hard upstream/${upstreamDefaultBranch}`);
-                      await log(`        git push --force origin ${upstreamDefaultBranch}`);
-                      await log('');
-                      await safeExit(1, 'Repository setup failed - fork sync failed');
-                    }
-                  } else {
-                    // Flag is not enabled - provide guidance
-                    await log('  💡 Your options:');
-                    await log('');
-                    await log('     Option 1: Delete your fork and recreate it (SIMPLEST)');
-                    await log(`              gh repo delete ${forkedRepo}`);
-                    await log('              Then run the solve command again - the fork will be recreated automatically');
-                    await log('              ⚠️  Only use this if your fork has no unique commits you need to preserve');
-                    await log('');
-                    await log('     Option 2: Enable automatic force-push (DANGEROUS)');
-                    await log('              Add --allow-fork-divergence-resolution-using-force-push-with-lease flag to your command');
-                    await log('              This will automatically sync your fork with upstream using force-with-lease');
-                    await log('              ⚠️  Overwrites fork history - any unique commits will be LOST');
-                    await log('');
-                    await log('     Option 3: Manually resolve the divergence');
-                    await log('              1. Decide if you need any commits unique to your fork');
-                    await log('              2. If yes, cherry-pick them after syncing');
-                    await log('              3. If no, manually force-push:');
-                    await log('                 git fetch upstream');
-                    await log(`                 git reset --hard upstream/${upstreamDefaultBranch}`);
-                    await log(`                 git push --force origin ${upstreamDefaultBranch}`);
-                    await log('');
-                    await log('  🔧 To proceed with auto-resolution, restart with:');
-                    await log(`     solve ${argv.url || argv['issue-url'] || argv._[0] || '<issue-url>'} --allow-fork-divergence-resolution-using-force-push-with-lease`);
-                    await log('');
-                    await safeExit(1, 'Repository setup halted - fork divergence requires user decision');
-                  }
-                } else {
-                  // Some other push error (not divergence-related)
-                  await log(`${formatAligned('❌', 'FATAL ERROR:', 'Failed to push updated default branch to fork')}`);
-                  await log(`${formatAligned('', 'Push error:', errorMsg)}`);
-                  await log(`${formatAligned('', 'Reason:', 'Fork must be updated or process must stop')}`);
-                  await log(`${formatAligned('', 'Solution draft:', 'Fork sync is required for proper workflow')}`);
-                  await log(`${formatAligned('', 'Next steps:', '1. Check GitHub permissions for the fork')}`);
-                  await log(`${formatAligned('', '', '2. Ensure fork is not protected')}`);
-                  await log(`${formatAligned('', '', '3. Try again after resolving fork issues')}`);
-                  await safeExit(1, 'Repository setup failed');
-                }
-              }
-
-              // Step 4: Return to the original branch if it was different
-              if (currentBranch !== upstreamDefaultBranch) {
-                await log(`${formatAligned('🔄', 'Returning to:', `${currentBranch} branch`)}`);
-                const returnResult = await $({ cwd: tempDir })`git checkout ${currentBranch}`;
-                if (returnResult.code === 0) {
-                  await log(`${formatAligned('✅', 'Branch restored:', `Back on ${currentBranch}`)}`);
-                } else {
-                  await log(`${formatAligned('⚠️', 'Warning:', `Failed to return to ${currentBranch}`)}`);
-                  // This is not fatal, continue with sync on default branch
-                }
-              }
-            } else {
-              await log(`${formatAligned('⚠️', 'Warning:', `Failed to sync ${upstreamDefaultBranch} with upstream`)}`);
-              if (syncResult.stderr) {
-                await log(`${formatAligned('', 'Sync error:', syncResult.stderr.toString().trim())}`);
-              }
-            }
-          }
-        } else {
-          await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get default branch name')}`);
-        }
-      } else {
-        await log(`${formatAligned('⚠️', 'Warning:', 'Failed to get current branch')}`);
-      }
-    } else {
-      await log(`${formatAligned('⚠️', 'Warning:', 'Failed to fetch upstream')}`);
-      if (fetchResult.stderr) {
-        await log(`${formatAligned('', 'Fetch error:', fetchResult.stderr.toString().trim())}`);
-      }
-    }
-  }
-};
+// Set up upstream remote and sync fork.
+// Extracted into solve.fork-sync.lib.mjs (#1893) to keep this file under the
+// 1500-line limit; re-exported here so existing importers keep working.
+export { setupUpstreamAndSync } from './solve.fork-sync.lib.mjs';
 
 // Set up pr-fork remote for continuing someone else's fork PR with --fork flag
 export const setupPrForkRemote = async (tempDir, argv, prForkOwner, repo, isContinueMode, owner = null) => {