Skip to content

fix: backport upstream reliability batch #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
e6qu merged 1 commit into from
Jun 6, 2026
Merged

fix: backport upstream reliability batch #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,26 +173,33 @@ Use `context_history` to navigate the edit DAG:
- Log all bugs in root `BUGS.md`, not per-package. Do not create `packages/*/BUGS.md`.
- Tracking docs (`PLAN.md`, `STATUS.md`, `WHAT_WE_DID.md`, `DO_NEXT.md`, `BUGS.md`, `GAP_ANALYSIS.md`, `UPSTREAM_STATUS.md`) live at repo root.
- Do not create tracking/status markdown files inside `packages/`.
- Update continuity docs at the end of every task, before committing the implementation PR.
- Write continuity docs in past tense so they remain accurate after the PR merges. Avoid wording like "PR is open", "waiting for merge", or "monitor checks" unless the user explicitly asks for a pre-merge handoff.
- Bundle continuity-doc updates with the same feature/fix PR that changed the work. Do not create a separate docs-only PR just to mark a prior PR merged or advance the phase; instead, make the docs accurate for the post-merge state before opening the implementation PR.

## Phase Methodology

Work follows the phased plan in `PLAN.md`. Each phase has exit criteria.

**Before starting a phase:**

1. Read `PLAN.md` to understand the phase scope and exit criteria
2. Read `GAP_ANALYSIS.md` to understand current state vs target
3. Read `DO_NEXT.md` for immediate actions
4. Read `BUGS.md` for any open issues that might affect the phase

**After completing a phase:**

1. Update `BUGS.md` — close fixed issues, add any new ones found
2. Update `STATUS.md` — refresh metrics (test count, error count, phase progress)
3. Update `WHAT_WE_DID.md` — add summary of work done
4. Update `GAP_ANALYSIS.md` — mark completed gaps, update current state
5. Update `DO_NEXT.md` — point to the next phase
6. Update `PLAN.md` — mark phase as complete, note PR number
6. Update `PLAN.md` — mark phase as complete, note that the PR merged, and leave next-phase instructions
7. Keep all continuity wording accurate after merge, even before the PR has actually merged locally

**When starting a new session:**

1. Review `STATUS.md` and `DO_NEXT.md` to orient
2. Verify tests pass and tsgo has 0 errors before making changes
3. Follow the current phase in `PLAN.md`
Expand Down
52 changes: 27 additions & 25 deletions BUGS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,57 +4,59 @@ Root bug tracker. Do not create per-package `BUGS.md` files.

## Open Security

| ID | Severity | Issue | Location | Status | Next action |
| --- | --- | --- | --- | --- | --- |
| S3 | High | Untrusted `.opencode/` autoloading for MCP/plugins | `packages/opencode/src/mcp`, `packages/opencode/src/plugin` | Mitigated with warning, not fully fixed | Design and implement workspace trust prompt before loading local MCP/plugin config |
| ID | Severity | Issue | Location | Status | Next action |
| --- | -------- | -------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| S3 | High | Untrusted `.opencode/` autoloading for MCP/plugins | `packages/opencode/src/mcp`, `packages/opencode/src/plugin` | Mitigated with warning, not fully fixed | Design and implement workspace trust prompt before loading local MCP/plugin config |

## Open Bugs

No confirmed open runtime bugs.

If a test, typecheck, lint, or runtime failure appears during upstream backports, either fix it in the same PR or add it here with enough detail for a fresh session to reproduce.

## Open Test Failures

No confirmed open test failures. A sandboxed full-suite run failed on 2026-06-06 with socket, watcher, dependency-resolution, and MCP OAuth browser symptoms, but the user-approved unsandboxed rerun passed with `1557 pass`, `8 skip`, `0 fail`.

## Open Edge Cases

| ID | Severity | Issue | Location | Status | Next action |
| --- | --- | --- | --- | --- | --- |
| E1 | Low | `sweep()` clock skew when `turnWhenSet > currentTurn` | `packages/opencode/src/context-edit/index.ts` | Deferred | Fix only if upstream/session turn ordering changes make this reachable |
| ID | Severity | Issue | Location | Status | Next action |
| --- | -------- | ----------------------------------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| E1 | Low | `sweep()` clock skew when `turnWhenSet > currentTurn` | `packages/opencode/src/context-edit/index.ts` | Deferred | Fix only if upstream/session turn ordering changes make this reachable |

## Open Code Quality

| ID | Severity | Issue | Location | Status | Next action |
| --- | --- | --- | --- | --- | --- |
| Q1 | Low | Empty `.catch(() => {})` blocks can hide real failures | Various | Deferred | Audit only files touched by current PR; keep intentional benign cleanup comments local |
| Q2 | Low | TODO/FIXME/HACK comments remain | Various | Deferred | Clean when touching affected code |
| Q4 | Medium | Copilot SDK chunk type safety is weak | `packages/opencode/src/provider/sdk/copilot/chat/openai-compatible-chat-language-model.ts` | Deferred | Replace boundary casts with explicit chunk types when touching Copilot provider |
| Q5 | Low | Direct `process.env` usage instead of `Env.set` | `packages/opencode/src/provider/provider.ts` | Deferred | Revisit during provider/runtime cleanup |
| ID | Severity | Issue | Location | Status | Next action |
| --- | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------- |
| Q1 | Low | Empty `.catch(() => {})` blocks can hide real failures | Various | Deferred | Audit only files touched by current PR; keep intentional benign cleanup comments local |
| Q2 | Low | TODO/FIXME/HACK comments remain | Various | Deferred | Clean when touching affected code |
| Q4 | Medium | Copilot SDK chunk type safety is weak | `packages/opencode/src/provider/sdk/copilot/chat/openai-compatible-chat-language-model.ts` | Deferred | Replace boundary casts with explicit chunk types when touching Copilot provider |
| Q5 | Low | Direct `process.env` usage instead of `Env.set` | `packages/opencode/src/provider/provider.ts` | Deferred | Revisit during provider/runtime cleanup |

## Upstream Backport Watchlist

These are not confirmed Frankencode bugs yet. PR 1 items have been ported or confirmed already present; the remaining watchlist is PR 2.
These were not confirmed Frankencode bugs yet. PR 1 and the portable PR 2 reliability items were ported, confirmed present, skipped, or deferred with reasons in `PLAN.md`.

| SHA | Area | Risk if missing |
| ----------- | ---------- | ------------------------------------------------------- |
| `e76cf967e` | Session | Interrupted assistant messages may not finalize cleanly |
| `ca28dd02e` | Compaction | Tail turns may be lost after summarization |

| SHA | Area | Risk if missing |
| --- | --- | --- |
| `2e6ac8ff4` | MCP | Failed/timed-out MCP connections may leak transports |
| `79d6b10d7` | MCP | Bad output schema refs may break MCP client loading |
| `01f031919` | LSP | TypeScript LSP may leak project state |
| `bc1840b19` | Web fetch | Failed fetches may leave timeout handles alive |
| `e26abd8da` | Shell tool | Truncation stream may remain open |
| `e76cf967e` | Session | Interrupted assistant messages may not finalize cleanly |
| `ca28dd02e` | Compaction | Tail turns may be lost after summarization |
The upstream shell truncation stream cleanup `e26abd8da` was skipped because Frankencode did not have upstream's `src/tool/shell.ts` truncation stream architecture.

## Fixed Summary

- PR 1 June upstream sync: prompt tool enables already present, `context_length_exceeded` overflow parsing already present, compaction transforms already present, LiteLLM `_noop` discouragement, subagent `todowrite` permissions, Bun `ZlibError` retryability, configured `model.limit.input`, `Tool.define()` wrapper mutation, read permission relative paths, and Plan Mode subagent deny inheritance.
- PR 2 June upstream sync: TypeScript LSP native `tsserver` args, MCP cleanup on failed connection/tool listing/refresh, MCP tolerant tool listing for invalid `outputSchema`, and webfetch timeout cleanup already present.
- Security fixed: S1 symlink containment bypass, S2 command injection in GitHub open flow, S4 unauthenticated non-loopback server, S5 sensitive `.env` read exposure.
- QA fixed: B53-B64, including CAS transaction/reference safety, edit graph transactions, synthetic ID collisions, plugin trigger errors, objective prompt escaping, MCP add return shape, text timing preservation, ripgrep JSON parse handling, and untracked line counts.
- Earlier fixed bugs: PRs #10-#33 in git history.

## Deferred

| ID | Severity | Issue | Location | Status |
| --- | --- | --- | --- | --- |
| B51 | Low | ID generator counter is not atomic | `packages/opencode/src/id/id.ts` | Acceptable while runtime is single-threaded; revisit if worker threads are added |
| ID | Severity | Issue | Location | Status |
| --- | -------- | ---------------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
| B51 | Low | ID generator counter is not atomic | `packages/opencode/src/id/id.ts` | Acceptable while runtime is single-threaded; revisit if worker threads are added |

## Notes For Fresh Sessions

Expand Down
39 changes: 18 additions & 21 deletions DO_NEXT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,30 @@
# Frankencode Do Next

Use this file as the first handoff target in fresh sessions. It should describe only the next actionable work.
Use this file as the first handoff target in fresh sessions. It described only the next actionable work after the PR 2 reliability slice.

## Immediate Task

Start PR 2 from `PLAN.md`: reliability fixes with more coupling.
Start Phase 3 from `PLAN.md`: evaluate small feature candidates that had direct CLI, MCP, provider, plugin, or TUI value and did not depend on upstream's V2 runtime or package split.

Start branch:
Best first candidates:

```sh
git switch dev
git pull --rebase origin dev
git switch -c fix/upstream-reliability-batch-2
```
- `ba57718b0` / #31054: non-interactive `mcp add`.
- `3f0ef9b71` / #31053: search in auth logout command.
- `519d34447` / #29493: plugin dispose hook.
- `f965db9e1` / #29484: provider `headerTimeout` config.

## Current State

- PR 1 merged as #37 at `e6c148f54`.
- PR #37 merged at `e6c148f54`.
- PR #38 merged at `9d8296e32` and established bundled continuity-doc updates.
- PR 2 reliability work ran on `fix/upstream-reliability-batch-2`.
- PR 2 ported TypeScript LSP native `tsserver` args and MCP cleanup/schema tolerance.
- PR 2 confirmed webfetch timeout cleanup was already present.
- PR 2 skipped upstream shell truncation cleanup as not applicable to Frankencode's current architecture.
- PR 2 deferred interrupted assistant finalization and compaction tail restoration for dedicated session/compaction work.
- `cd packages/opencode && bun typecheck` passed on 2026-06-06.
- `cd packages/opencode && bun test --timeout 30000` passed on 2026-06-06 with `1554 pass`, `8 skip`, `0 fail`.
- Full tests were run outside the sandbox because socket tests failed sandboxed with `EADDRINUSE`.
- `cd packages/opencode && bun test test/lsp/server.test.ts test/mcp/lifecycle.test.ts test/tool/webfetch.test.ts` passed on 2026-06-06 with `6 pass`, `0 fail`.
- User-approved unsandboxed `cd packages/opencode && bun test --timeout 30000` passed on 2026-06-06 with `1557 pass`, `8 skip`, `0 fail`.

## Next Commands

Expand All @@ -30,17 +35,9 @@ git status --short --branch
git fetch origin upstream
git switch dev
git pull --rebase origin dev
git switch -c fix/upstream-reliability-batch-2
git switch -c <type>/<short-topic>
```

Then inspect and port the PR 2 queue:

- MCP transport cleanup.
- MCP output schema `$ref` tolerance.
- TypeScript LSP native project config.
- Webfetch timeout cleanup.
- Shell truncation stream cleanup.
- Interrupted assistant finalization.
- Compaction tail restoration.
Then inspect the selected Phase 3 upstream diff manually and update continuity docs at the end of the implementation PR in past tense.

Do not push directly to `dev`.
75 changes: 40 additions & 35 deletions GAP_ANALYSIS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,40 @@
# Frankencode — Gap Analysis

**Date:** 2026-03-22

## All Phases Complete

| Phase | Goal | Status |
|-------|------|--------|
| 1 | Security fixes (S1-S5) | Done — 4 fixed, 1 mitigated |
| 2 | High-priority upstream fixes | Done — 5 backported |
| 3+4 | Quality + community fixes | Done — OpenTUI 0.1.88, agent ordering |
| 5 | Remaining tests | Done — 24 new tests (filterEdited, filterEphemeral, validation) |
| 6 | Effect behavioral analysis | Done — 0 need reimplementation |

## Remaining Gaps (Backlog)

| Gap | Priority | Notes |
|-----|----------|-------|
| S3 workspace trust prompt | Med | Warning log added; full VS Code-style trust model planned |
| TUI edit indicators | Low | No visual indicator for hidden/replaced/annotated parts |
| CAS GC improvements | Low | Basic GC exists; size limits and age-based cleanup not implemented |
| Upstream re-sync | Ongoing | Cherry-pick new fixes as they land; 162 commits analyzed |

## Permanently Out of Scope

- Desktop/Electron app
- Bun→Node portability refactors
- Zen platform changes

## Cross-references

- [PLAN.md](PLAN.md) — completed roadmap
- [DO_NEXT.md](DO_NEXT.md) — backlog items
- [UPSTREAM_STATUS.md](UPSTREAM_STATUS.md) — full catalogue with Phase 6 analysis
- [docs/SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) — CVEs and vulnerability details
# Frankencode Gap Analysis

**Date:** 2026-06-06

## Current Gaps

| Gap | Priority | Status | Next action |
| ---------------------------------- | -------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
| S3 workspace trust prompt | Medium | Warning mitigation remained in place | Design a workspace trust prompt before loading local MCP/plugin config |
| Interrupted assistant finalization | Medium | Deferred from PR 2 | Port upstream #27254 only with focused session interruption coverage |
| Compaction tail restoration | Medium | Deferred from PR 2 | Port upstream #27145 only after mapping Frankencode's current compaction flow |
| TUI edit indicators | Low | Backlog | Add visual indicators for hidden/replaced/annotated parts when touching TUI context views |
| CAS GC improvements | Low | Backlog | Add size and age policies after storage pressure requirements are defined |

## Completed Maintenance

| Phase | Goal | Status |
| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| March Phase 1 | Security fixes S1-S5 | Done; 4 fixed, S3 mitigated |
| March Phase 2 | High-priority upstream fixes | Done |
| March Phase 3-4 | Quality and community fixes | Done |
| March Phase 5 | Remaining tests | Done |
| March Phase 6 | Effect behavioral analysis | Done; 0 reimplementations needed |
| June PR 1 | Low-risk upstream bugfix backports | Done and merged as #37 |
| June PR 2 | Reliability fixes with more coupling | Done; portable LSP/MCP fixes landed and divergent session/compaction items were deferred |

## Permanently Out Of Scope

- Desktop/Electron app.
- Bun-to-Node portability refactors unless Frankencode adopted a Node runtime target.
- Zen platform changes.
- Generated-only, release-only, nix-only, and CI-only upstream churn unless it directly unblocked Frankencode.

## Cross-References

- [PLAN.md](PLAN.md) tracked phased upstream maintenance.
- [DO_NEXT.md](DO_NEXT.md) identified the next actionable work.
- [BUGS.md](BUGS.md) tracked confirmed bugs and deferred risks.
- [UPSTREAM_STATUS.md](UPSTREAM_STATUS.md) retained the historical March catalogue.
- [docs/SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) held security details.
Loading
Loading