# Reported issues for okffs

Pod holds 16 of 24 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [okffs](/mcp/okffs).

## Most discussed

### commit_and_update: comment-step failure after successful commit+push escapes as raw 'MCP error -32603: fetch failed'

## Incident

2026-08-12, greyvensteins repo, working issue neturely/greyvensteins#36. A `commit_and_update` call ran >120s, was backgrounded by the harness, then failed with:

```
Task failed: MCP error -32603: fetch failed
```

By that point the tool had already **committed and pushed** to the issue branch. Only the final issue-comment step had failed (transient GitHub API error — `update_project_status` minutes before and `comment_issue` minutes after both succeeded). None of that was visible 

[Read the thread](https://github.com/neturely/okffs/issues/284) · 2026-08-12 · closed · 5 comments

### Silent auto-PR failure in create_issue - swallowed to stderr, retry on 422

## Summary

When `OKFFS_AUTO_PR=true`, `create_issue` reports success but can silently open **no** draft PR, with no indication in the tool response. The failure is caught non-fatally and only `console.warn`'d to stderr, so the tool looks like it half-succeeded with no explanation - the user only notices the missing `Draft PR:` line.

Observed in the wild while setting up okffs in a consumer repo: `create_issue` succeeded, no draft PR appeared. Re-running the identical `POST /pulls` seconds late

[Read the thread](https://github.com/neturely/okffs/issues/247) · 2026-07-11 · closed · 5 comments

### Autopilot / "minimum interference" mode — autonomous issue → develop-PR with a decisions report

## Concept

An opt-in **autopilot** (a.k.a. "minimum interference") mode for a work session. When active, the agent stops asking the user to choose between options and instead **takes the recommended/logical choice at each fork**, using the authorization okffs already grants, and drives an issue **all the way to a PR into the base branch (`develop`)** — then posts a short **decisions report** of the choices it made.

Activated per-request (a phrase like "…minimum interference" / "fully handle th

[Read the thread](https://github.com/neturely/okffs/issues/238) · 2026-07-08 · closed · 5 comments

### Surface promotion-PR review feedback proactively — okffs should detect and drive the Copilot-review fix loop, not wait to be asked

## Problem

The promotion flow requests a Copilot review on the gate PR (`OKFFS_PROMOTION_AUTO_REVIEW` + `OKFFS_PROMOTION_REVIEWERS`), but nothing in okffs ever *checks back* for the resulting feedback. The review lands on GitHub, and in **every repo using okffs** the user has to notice it themselves and prompt the agent ("there are comments on the Copilot review — go fix them") before the `list_pr_review_comments` → fix → `fix_into_base` → reply/resolve loop kicks in. Reported after the okffs 0

[Read the thread](https://github.com/neturely/okffs/issues/302) · 2026-08-21 · closed · 4 comments

### update_issue with a body wipes okffs's own metadata (**Branch:** line, ## Relationships), breaking commit_and_update

## Problem

`update_issue` PATCHes `body` straight through to the GitHub REST API with no awareness of the metadata okffs itself writes into the issue body. Any body rewrite therefore silently destroys:

- the `**Branch:**` branch-link line written by `create_issue` (`src/tools/create_issue.ts:124`, `create_issues_from_list.ts:96`, `plan.ts:173`)
- the **`## Relationships`** section written by `link_issues` (`src/tools/link_issues.ts:31-35`)

Losing the **Branch:** line breaks every downstream t

[Read the thread](https://github.com/neturely/okffs/issues/295) · 2026-08-20 · closed · 4 comments

### commit_and_update is not idempotent on retry — clean-tree "nothing to commit" reported as failure

## Problem

When a `commit_and_update` call times out client-side (MCP `-32603 fetch failed`) but the server-side work actually completed (stage, commit, and push all succeeded), the natural retry fails: `git commit` runs on a now-clean tree, exits non-zero with "nothing to commit, working tree clean", and the handler bails with `commit_and_update failed: Command failed: git commit …` (`src/tools/commit_and_update.ts` — the catch around the stage/commit/push block). This is a false failure, and 

[Read the thread](https://github.com/neturely/okffs/issues/269) · 2026-08-10 · closed · 4 comments

### create_issue takes `description` but update_issue takes `body` — unify the param name for the issue body

## Problem

The create/update tool pair names the same field differently:

- `create_issue` (and the per-task objects in `plan` / `create_issues_from_list`) call the issue body **`description`**
- `update_issue` calls it **`body`** (matching the GitHub REST field it PATCHes)

Same field, opposite names across the pair — the agent has to remember which tool uses which. This is the same cross-tool consistency class as #278/#279, where `update_project_status`'s `issue` param was renamed to `issue_n

[Read the thread](https://github.com/neturely/okffs/issues/282) · 2026-08-11 · closed · 3 comments

### Harden reply_to_review_comment against reply-without-resolve footgun

## Problem

`reply_to_review_comment` and `resolve_review_thread` are fully separate calls: replying does nothing toward resolving a thread (`src/github.ts:542` is a pure REST `in_reply_to` POST). This means an agent can post replies and silently skip the resolve step — even when the operator has set `OKFFS_RESOLVE_THREADS=true` to signal "I want addressed threads resolved." The operator's intent is then half-honoured with no error.

The tool descriptions don't guard against this:
- `reply_to_re

[Read the thread](https://github.com/neturely/okffs/issues/230) · 2026-07-08 · closed · 3 comments

## Most recent

### Conversational in-Claude-Code setup (/okffs:setup prompt + configure tool) with upgrade-aware nudge

Follow-up to #240 (the `okffs setup` CLI wizard). The CLI wizard is interactive and can only run in a real terminal — it can't run inside Claude Code (the `!` bang and tools both run children with piped, non-TTY stdio). This issue adds a **conversational** setup path that works *inside* Claude Code, plus a proactive **upgrade nudge**.

## Motivation

- A new user who wires up `.mcp.json` and never opens a terminal has no in-chat way to configure okffs beyond editing `.env` by hand.
- After an ok

[Read the thread](https://github.com/neturely/okffs/issues/242) · 2026-07-11 · closed · 2 comments

### Add update_issue tool — mutate title/assignees/labels/milestone on an existing issue

## Problem

okffs can set core issue fields (title, assignees, labels, milestone) **only at creation time** via `create_issue`. There is no tool to mutate them afterward:

- `create_issue` — sets title/assignees/labels/milestone at creation only.
- `set_issue_fields` — covers board **Priority/Effort** only.
- No `update_issue` / `edit_issue` exists.

So editing an existing issue's title or assignee has no okffs path, forcing a fallback to `gh issue edit`. That's exactly the case our conventions 

[Read the thread](https://github.com/neturely/okffs/issues/203) · 2026-07-05 · closed · 2 comments

### Strengthen guidance so Claude prefers okffs tools over raw gh/git

In practice Claude still defaults to raw `gh`/`git` even though okffs should take priority (okffs authenticates with a better-scoped PAT; raw gh uses whatever ambient token, often the wrong one, and skips okffs conventions/board/guards). Harden the guidance so Claude reaches for okffs tools first.

Changes:
- Sharpen the MCP server instructions (src/index.ts) with explicit action → okffs tool mappings, including 'Promotion/release gate (develop→main): promote_branch'.
- Make the 'why' concrete (

[Read the thread](https://github.com/neturely/okffs/issues/183) · 2026-07-05 · closed · 2 comments

### Add promote_branch tool: issue-less develop→main PR added to the board

Add a new okffs tool `promote_branch` that opens the release/promotion PR from OKFFS_BASE_BRANCH into the repo default (or OKFFS_PROTECTED_BRANCH) — e.g. develop→main. It is deliberately issue-less: no issue lookup, no Closes #N.

Behaviour:
- Open the head→base PR (head = OKFFS_BASE_BRANCH, base = default/protected branch).
- No confirmation prompt — opening is safe; the merge stays with the user (depends on the corrected protected-branch semantics).
- Add the PR ITSELF to the Projects v2 board

[Read the thread](https://github.com/neturely/okffs/issues/182) · 2026-07-05 · closed · 2 comments

### Provide MCP server `instructions` so agents prefer okffs tools and adopt new features on upgrade

## Problem

When okffs ships a new tool or behaviour, host agents (Claude Code, etc.) keep defaulting to **old behaviour** — hand-rolling `gh`/GraphQL for things okffs now has tools for, or not discovering new tools at all. There's no mechanism telling the agent "prefer these tools; here's how this server works." The only signal is per-tool `description`s (easy to overlook) and per-repo `CLAUDE.md` guidance (stale, hand-maintained, doesn't travel with the package).

Concrete recurring symptom: a

[Read the thread](https://github.com/neturely/okffs/issues/169) · 2026-07-04 · closed · 2 comments

### publish.yml: create the GitHub Release automatically on stable tags

## Problem

The publish workflow pushes to npm and the MCP Registry on a `v*.*.*` tag, but does **not** create the corresponding GitHub Release — that's left as a manual `gh release create`. It's illogical to automate the harder publishes and leave the Release manual; it gets forgotten or done by hand inconsistently.

## Proposal

Add a step to `.github/workflows/publish.yml` (stable releases only) that creates the GitHub Release from the pushed tag, using the matching section of `CHANGELOG.md` 

[Read the thread](https://github.com/neturely/okffs/issues/156) · 2026-07-04 · closed · 2 comments

### Add OKFFS_PROTECTED_BRANCH — hard confirmation gate before okffs promotes into a protected branch

## Problem

okffs's assisted flows can walk an agent all the way to a full release (merge into `main`, then tag → CI npm publish) with no forced human checkpoint. In practice an agent can read broad authorization from an earlier message and promote to the release branch + publish without the maintainer checking `main` first. There is currently no okffs-level guard that says "this branch is special — stop and get explicit confirmation."

## Proposal

Add `OKFFS_PROTECTED_BRANCH` (e.g. `main`; uns

[Read the thread](https://github.com/neturely/okffs/issues/152) · 2026-07-04 · closed · 3 comments

### Phase 6: deploy workflow — .github/workflows/deploy-site.yml (FTP to Knowhost)

Add the GitHub Actions workflow that builds and FTP-deploys the site.

### `.github/workflows/deploy-site.yml`
- **Trigger:** push to `main`, path filter `site/**`
- **Steps:** checkout → setup Node → `cd site && npm ci && npm run build` → deploy `site/dist` via `SamKirkland/FTP-Deploy-Action@v4.3.5`
- **FTP inputs from secrets:** `secrets.FTP_SERVER`, `secrets.FTP_USERNAME`, `secrets.FTP_PASSWORD`
- **`server-dir`:** placeholder (e.g. `./`) with a comment noting the actual Knowhost path for the

[Read the thread](https://github.com/neturely/okffs/issues/114) · 2026-07-03 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/neturely/okffs/issues).