UPSTREAM_SYNC.md

Upstream Sync Guide

Lash is a fork of anomalyco/opencode. This document describes how to merge upstream changes into the lash branch.

Overview

Upstream remote: upstream → https://github.com/anomalyco/opencode.git
Target branch: lash — lash is the GitHub default and the working branch. Sync PRs, fixes, and releases target lash, never dev. (release-lash.ts only force-releases on lash.) 2026-09-04: syncs through PR #43 had drifted onto dev; dev was merged back into lash at aa19cdfb11 and dev is no longer a working branch.
Merge target: upstream/dev

Quick Sync (recurring)

# 1. Fetch upstream
git fetch upstream

# 2. Merge (no fast-forward, no auto-commit so conflicts can be resolved)
git merge upstream/dev --no-commit --no-ff

# 3. Resolve conflicts (see "Conflict Playbook" below)
# ... fix files ...

# 4. Regenerate lockfile
bun install

# 5. Stage and commit
git add -A
git commit -m "merge: bring upstream dev into lash"

Conflict Playbook

Every upstream merge tends to produce the same categories of conflicts. This section documents how to resolve each.

1. Package version conflicts (`packages/*/package.json`, `sdks/vscode/package.json`)

Pattern: version field differs between lash (1.7.x) and upstream (1.x.x).

Resolution: Keep lash's version (1.7.x). All packages are versioned together.

# Automated fix — keep lash version:
for f in packages/*/package.json sdks/vscode/package.json; do
  python3 -c "
import re, sys
content = open('$f').read()
content = re.sub(
  r'<<<<<<< HEAD\n  \"version\": \"(1\.7\.[^\"]+)\",\n.*?>>>>>>> upstream/dev\n',
  r'  \"version\": \"\1\",\n',
  content, flags=re.DOTALL
)
open('$f', 'w').write(content)
"
done

2. Root `package.json` — patchedDependencies

Pattern: Upstream replaces the patchedDependencies entries; lash adds a funding block.

Resolution: Take upstream's patches + keep lash's funding block.

3. `packages/extensions/zed/extension.toml`

Pattern: Version + archive URLs differ.

Resolution: Keep lash's version (the archive URLs point to anomalyco/opencode — update them to lacymorrow/lash when publishing to Zed marketplace).

4. `packages/sdk/js/src/v2/gen/types.gen.ts`

Pattern: Upstream reorganizes generated types; lash adds EventCwdUpdated.

Resolution:

Take the upstream's large block that reorganizes types (keep nothing from our HEAD section except EventCwdUpdated)
Add EventCwdUpdated to the Event union type after EventPermissionReplied

// Keep this type definition:
export type EventCwdUpdated = {
  type: "cwd.updated"
  properties: {
    cwd: string
  }
}

// In the Event union, add:
  | EventCwdUpdated

5. `packages/opencode/src/server/server.ts`

Pattern: Upstream reorganizes imports.

Resolution: Take upstream's empty section (upstream moved imports to other files). Our old getCwd, CwdEvent import here was stale and unused.

6. `packages/opencode/src/tool/bash.ts`

Pattern: The cwd variable in execute().

Resolution: Combine both — use getCwd() and resolvePath() together:

// WRONG (upstream only):
const cwd = params.workdir ? await resolvePath(params.workdir, Instance.directory, shell) : Instance.directory

// WRONG (lash only):
const cwd = params.workdir || getCwd()

// CORRECT (combined):
const cwd = params.workdir ? await resolvePath(params.workdir, getCwd(), shell) : getCwd()

7. `packages/opencode/src/session/prompt.ts` (MAJOR)

Upstream completely rewrites this file using Effect patterns (1907 lines vs the old ~2500 line async/await version).

Resolution: Take upstream's entire version (git checkout --theirs), then apply lash changes:

git checkout --theirs packages/opencode/src/session/prompt.ts

Then manually add:

a) Import (after import { Shell } from "@/shell/shell"):

import { getCwd, setCwd, detectNaturalLanguage } from "@shell-mode"

b) Replace ctx.directory with getCwd() in all path objects:

python3 -c "
content = open('packages/opencode/src/session/prompt.ts').read()
content = content.replace('path: { cwd: ctx.directory, root: ctx.worktree }', 'path: { cwd: getCwd(), root: ctx.worktree }')
open('packages/opencode/src/session/prompt.ts', 'w').write(content)
"

c) In the bash execution function, change const cwd = ctx.directory to const cwd = getCwd()

d) Replace the simple bash invocations with sentinel-wrapped versions that output the new cwd after each command, then parse and call setCwd(newCwd) in the finish Effect.

e) Add detectNaturalLanguage() call in the finish Effect after parsing the sentinel.

See commit e95356aec for the full diff of these changes.

8. `packages/opencode/src/cli/cmd/tui/app.tsx`

Pattern: Upstream adds createCliRenderer, TuiPluginRuntime, plugin system.

Resolution:

Take both imports (lash's ExecutionModeProvider, WorkingDirProvider AND upstream's createTuiApi, TuiPluginRuntime)
Take upstream's render tree but add our providers around <App />:

<PromptRefProvider>
  <ExecutionModeProvider>    {/* lash addition */}
    <WorkingDirProvider>     {/* lash addition */}
      <App onSnapshot={input.onSnapshot} />
    </WorkingDirProvider>
  </ExecutionModeProvider>
</PromptRefProvider>

9. `packages/opencode/src/cli/cmd/tui/routes/home.tsx`

Pattern: Upstream adds TuiPluginRuntime.Slot wrappers for extensibility.

Resolution: Take upstream's structure (with plugin slots and placeholders prop) and add showWorkingDirectory={false} to the Prompt in the home_prompt slot.

10. `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` (MAJOR)

Resolution: Take upstream's version (git checkout --theirs), then add:

RGBA to opentui/core imports
DialogExecutionMode import
@tui-integration imports (useExecutionMode, handleModeToggleKey, determineRouting, shell completion hooks)
ExecutionMode from @shell-mode
showWorkingDirectory?: boolean prop
completionCycle: CompletionCycleState | null in store type + init
executionMode = useExecutionMode() context in function body
shortenedWorkingDir computed memo
modePrefixColor computed memo
determineRouting() in submit function (replaces store.mode === "shell" check)
handleModeToggleKey() in onKeyDown handler
DialogExecutionMode in command registry
Working directory display in footer fallback
Mode toggle hint in footer hints area

Double left border — upstream only has a single border. Add the execution mode inner border using a row layout (not nested borders — see below):

<box border={["left"]} borderColor={borderHighlight()} customBorderChars={{...SplitBorder.customBorderChars, bottomLeft: "╹"}}>
  <box flexDirection="row">
    <box
      width={1}
      alignSelf="stretch"
      border={["left"]}
      borderColor={modePrefixColor()}
      customBorderChars={{ ...SplitBorder.customBorderChars }}
    />
    <box paddingLeft={2} paddingRight={2} paddingTop={1} flexShrink={0} backgroundColor={theme.backgroundElement} flexGrow={1}>
      {/* textarea + footer */}
    </box>
  </box>
</box>

Why row layout? Nesting border={["left"]} boxes causes the inner border to appear 1–2 rows shorter than the outer because Yoga sizes each box independently. Using width={1} + alignSelf="stretch" in a row container guarantees both bars span identical rows.

12. `packages/opencode/src/config/keybinds.ts`

Pattern: Upstream may reassign agent_cycle to tab. Lash remaps Tab to shell autocomplete.

Resolution: Ensure agent_cycle is on shift+tab, NOT tab:

agent_cycle: keybind("shift+tab", "Next agent"),
agent_cycle_reverse: keybind("none", "Previous agent"),

Tab is handled in onKeyDown in prompt/index.tsx via handleShellTabCompletion().

13. `bun.lock`

Resolution: Do NOT run bun install while the lockfile still contains conflict markers — bun silently re-resolves every ^-ranged dependency, floating packages far past what either side pinned. (2026-07-20: this floated storybook-solidjs-vite 10.1.1 → 10.6.0, whose new Solid-version detection broke the storybook CI build and OOM'd local builds.)

Instead, restore a clean base lockfile first, then install:

git checkout HEAD -- bun.lock   # pre-merge lash lockfile (or upstream/dev -- bun.lock if theirs is closer)
bun install                      # only resolves the actual package.json deltas
git add bun.lock

Then verify nothing unexpected floated:

git diff --cached bun.lock | grep -E '^[+-]' | grep -vE 'workspace:|1\.7\.' | head -50

Post-Merge QA Checklist

Run through this visually after every merge commit, before closing the sync issue.

Prompt border

Two left border bars visible: outer bar = agent color, inner bar = execution mode color
Both bars are the same height — no gap at top or bottom of the inner bar
Outer bar shows a ╹ connector at the bottom join

Keybinds

Tab → triggers shell autocomplete (shows completions or cycles them)
Shift+Tab → cycles agents (Build → Plan → …)
Ctrl+Space → cycles execution modes (agent → shell → auto)
Enter → submits prompt; Shift+Enter → inserts newline

Execution mode indicator

Footer shows mode name in execution mode color (e.g. ctrl+space agent)
Switching modes updates both the inner border color and the footer label

Shell mode

Typing ! at start of prompt switches to shell mode (blue border)
Pressing Escape from shell mode returns to normal mode
Running a command in shell mode updates the working directory in the footer

Working directory

Footer left side shows shortened cwd (e.g. ~/repo/lash)
Running cd <dir> in shell mode updates the displayed cwd

Typecheck

cd packages/opencode && bun run typecheck

Zero errors required before closing the sync issue.

What Lash Preserves (invariants)

These features must always be preserved through upstream merges:

Feature	Files	Purpose
`getCwd()` / `setCwd()`	`plugin/shell-mode/cwd.ts`	Shell cwd tracking
`detectNaturalLanguage()`	`plugin/shell-mode/natural-language.ts`	NL detection
`ExecutionMode` (shell/agent/auto)	`plugin/shell-mode/mode.ts`	Mode switching
`ExecutionModeProvider`	`plugin/tui-integration/execution-mode-provider.tsx`	TUI context
`WorkingDirProvider`	`plugin/tui-integration/working-dir-provider.tsx`	TUI cwd display
`handleModeToggleKey()`	`plugin/tui-integration/hooks.ts`	ctrl+space handler
`determineRouting()`	`plugin/tui-integration/hooks.ts`	Shell vs agent routing
`cwd sentinel` in bash	`src/session/prompt.ts`	Cwd tracking after cd
ctrl+space mode toggle	`packages/tui/src/component/prompt/index.tsx` (`prompt.mode.toggle` binding)	replaced `mode_toggle` keybind after 2026-07-07 TUI move
`agent_cycle` keybind	`packages/tui/src/config/keybind.ts`	shift+tab (NOT tab)
Double left border	`packages/tui/src/component/prompt/index.tsx`	Row layout, not nested
`EventCwdUpdated`	`sdk/js/src/v2/gen/types.gen.ts`	SDK type for cwd event
cwd in `path.*` field	`src/session/prompt.ts`	Shows cwd in messages

Automating the Sync (future)

To automate weekly syncs, add a GitHub Action:

# .github/workflows/upstream-sync.yml
name: Upstream Sync
on:
  schedule:
    - cron: '0 6 * * 1'  # Every Monday 6am UTC
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0
      - run: git remote add upstream https://github.com/anomalyco/opencode.git
      - run: git fetch upstream
      - run: git config user.email "lacy@example.com"
      - run: git config user.name "Lacy Bot"
      - run: |
          git merge upstream/dev --no-commit --no-ff || true
          # Check if there are conflicts
          if git diff --name-only --diff-filter=U | grep -q .; then
            echo "CONFLICTS=true" >> $GITHUB_ENV
          fi
      - name: Open PR if merge succeeds
        if: env.CONFLICTS != 'true'
        run: |
          git commit -m "chore: merge upstream dev"
          git push origin HEAD:upstream-sync-$(date +%Y%m%d)
          gh pr create --title "Upstream sync $(date +%Y-%m-%d)" ...

For conflict-free or simple merges, this can be fully automated. Conflicted merges (like prompt.ts refactors) require manual resolution — create a PR instead and resolve manually.

Sync History

Date	Upstream commits merged	Conflicts	Notes
2026-04-02	673 (cf7ca9b2f → 92e820fdc)	28 files	Major Effect rewrite of prompt.ts
2026-04-28	(QA only — no new merge)	—	LAC-163: found 3 regressions post-merge: missing double border, wrong Tab keybind, border height mismatch. Fixed in commits bde00fa30, 85faf49fc, 9d7ac27c1. Added this QA checklist.
2026-06-26	629 (catch-up)	—	PR #31 merged.
2026-06-30	68	escalated → LAC-2496	PR #32 opened; later superseded by PR #39.
2026-07-07	195 (→ v1.17.15)	prompt/index.tsx re-architecture	LAC-2556: merge completed on-branch; run died in API outage before PR. mode_toggle/handleModeToggleKey replaced by direct ctrl+space `prompt.mode.toggle` binding; TUI moved to `packages/tui/`.
2026-07-13	90 (→ v1.17.18)	15 version bumps, TEAM_MEMBERS, 1 hunk in prompt/index.tsx	LAC-2739: consolidated PR #39 (06-30 + 07-07 + 07-13). Kept lash `shortenedWorkingDir` footer over upstream's session-directory display. Typecheck 30/30.
2026-07-20	153 (→ v1.18.3)	15 version bumps, bun.lock	LAC-2865: merged into PR #39 branch (dev still awaiting PR #39 merge). Also merged origin/dev (PR #40 Windows deflake). No complex conflicts; invariants verified.
2026-07-27	167 (→ v1.18.7)	15 version bumps, bun.lock	LAC-3102: built on LAC-2739 branch (PR #39 still open). Version conflicts auto-resolved (kept lash 1.7.x). Typecheck gate: 0 errors. No changes to prompt.ts/keybinds.ts/types.gen.ts. agent_cycle=shift+tab verified.
2026-08-04	132 (→ v1.18.13)	15 version bumps, bun.lock	LAC-3206: continued on LAC-3102 branch (PR #42), which fully contains PR #39 → #39 superseded/closable. All conflicts standard (kept lash 1.7.13; bun.lock regenerated). Flagged complex files (prompt.ts/app.tsx/prompt/index.tsx/types.gen.ts/keybinds.ts) auto-merged clean — no escalation. agent_cycle=shift+tab verified. Backlog risk: sync PRs (#39→#42) have not landed on dev since 07-13; escalate merge decision.
2026-08-10	59 (→ v1.18.16)	15 version bumps, bun.lock	LAC-3264: continued on LAC-3102 branch (PR #42, still open). Standard conflicts only (kept lash 1.7.13; bun.lock regenerated from clean base — delta was internal versions + upstream's new @ai-sdk/openai-compatible@2.0.41 patch entry). Complex files: prompt.ts got 1 upstream fix hunk (orphan detection via parentID), prompt/index.tsx got cursor-style config (#32295); keybind.ts/app.tsx/types.gen.ts untouched. All invariants verified; agent_cycle=shift+tab. Typecheck 30/30. Backlog risk persists: PR #42 unmerged since 07-13 lineage.
2026-09-04	(audit — no new upstream merge)	—	Merged PR #41 + PR #43 into `dev`, then `dev` → `lash` (`aa19cdfb11`, clean). Added `lash` to test/typecheck/nix-eval workflow branch filters. Routine repointed to target `lash`. Open: LAC-3268 visual QA, LAC-2396 release 1.7.14, LAC-3732 cwd-footer defect.
2026-08-17	62 (→ v1.18.18)	version bumps, bun.lock, beta.yml	LAC-3333: fresh branch from dev (PR #42 merged 2026-08-10). Standard conflicts only (kept lash 1.7.13; bun.lock regenerated from upstream base). Complex files: all 5 (prompt.ts/app.tsx/prompt/index.tsx/types.gen.ts/keybinds.ts) auto-merged clean — no escalation. EventCwdUpdated in types.gen.ts ✓, agent_cycle=shift+tab ✓, getCwd() in prompt.ts ✓. Typecheck 30/30. PR #43.
2026-08-24	113 (→ v1.18.21)	15 version bumps, bun.lock	LAC-3413: continued on LAC-3333 branch (PR #43 still open). Standard conflicts only (kept lash 1.7.13; bun.lock regenerated from upstream base). Gotcha caught: `git checkout --ours` on packages/opencode/package.json dropped upstream's @ai-sdk/amazon-bedrock 4.0.158 + google-vertex 4.0.181 pin bumps — re-applied manually. When verifying version-only conflicts, diff merge-base→upstream per file; files reverted to ours vanish from `git diff --cached`. Complex files: prompt.ts got 1 fix hunk (continue unknown finish responses #43892), types.gen.ts 2 lines (upgrade endpoint #44686) — both auto-merged clean, no escalation. agent_cycle=shift+tab ✓, EventCwdUpdated ✓, getCwd() ✓. Typecheck 30/30.
2026-08-31	62 (→ v1.18.25)	15 version bumps, bun.lock	LAC-3587: continued on LAC-3333 branch (PR #43 still open). Standard conflicts only — each package.json had a single version-line hunk (resolved in-place keeping lash 1.7.13, upstream dep changes auto-merged outside the hunk; no `checkout --ours`, so no pin-drop gotcha). bun.lock regenerated from upstream base; float check clean (only upstream's own 1.18.25 bumps + number-flow add / d3-geo removals). Complex files (prompt.ts/app.tsx/prompt/index.tsx/types.gen.ts/keybind.ts) untouched by upstream this week. agent_cycle=shift+tab ✓, EventCwdUpdated ✓, getCwd(ctx.directory) ✓, detectNaturalLanguage ✓. Typecheck 30/30. Backlog note: PR #43 now carries 3 weeks (08-17/08-24/08-31) awaiting merge by Lacy.

Navigation Menu

Repository navigation

Upstream Sync Guide

Overview

Quick Sync (recurring)

Conflict Playbook

1. Package version conflicts (`packages/*/package.json`, `sdks/vscode/package.json`)

2. Root `package.json` — patchedDependencies

3. `packages/extensions/zed/extension.toml`

4. `packages/sdk/js/src/v2/gen/types.gen.ts`

5. `packages/opencode/src/server/server.ts`

6. `packages/opencode/src/tool/bash.ts`

7. `packages/opencode/src/session/prompt.ts` (MAJOR)

8. `packages/opencode/src/cli/cmd/tui/app.tsx`

9. `packages/opencode/src/cli/cmd/tui/routes/home.tsx`

10. `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` (MAJOR)

12. `packages/opencode/src/config/keybinds.ts`

13. `bun.lock`

Post-Merge QA Checklist

Prompt border

Keybinds

Execution mode indicator

Shell mode

Working directory

Typecheck

What Lash Preserves (invariants)

Automating the Sync (future)

Sync History

FilesExpand file tree

UPSTREAM_SYNC.md

Latest commit

History

UPSTREAM_SYNC.md

File metadata and controls

Upstream Sync Guide

Overview

Quick Sync (recurring)

Conflict Playbook

1. Package version conflicts (packages/*/package.json, sdks/vscode/package.json)

2. Root package.json — patchedDependencies

3. packages/extensions/zed/extension.toml

4. packages/sdk/js/src/v2/gen/types.gen.ts

5. packages/opencode/src/server/server.ts

6. packages/opencode/src/tool/bash.ts

7. packages/opencode/src/session/prompt.ts (MAJOR)

8. packages/opencode/src/cli/cmd/tui/app.tsx

9. packages/opencode/src/cli/cmd/tui/routes/home.tsx

10. packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx (MAJOR)

12. packages/opencode/src/config/keybinds.ts

13. bun.lock

Post-Merge QA Checklist

Prompt border

Keybinds

Execution mode indicator

Shell mode

Working directory

Typecheck

What Lash Preserves (invariants)

Automating the Sync (future)

Sync History

1. Package version conflicts (`packages/*/package.json`, `sdks/vscode/package.json`)

2. Root `package.json` — patchedDependencies

3. `packages/extensions/zed/extension.toml`

4. `packages/sdk/js/src/v2/gen/types.gen.ts`

5. `packages/opencode/src/server/server.ts`

6. `packages/opencode/src/tool/bash.ts`

7. `packages/opencode/src/session/prompt.ts` (MAJOR)

8. `packages/opencode/src/cli/cmd/tui/app.tsx`

9. `packages/opencode/src/cli/cmd/tui/routes/home.tsx`

10. `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` (MAJOR)

12. `packages/opencode/src/config/keybinds.ts`

13. `bun.lock`