## Description
Adds a top-level `FAQ.md` covering the questions most likely to come up
for someone landing on this repo for the first time, especially someone
planning to contribute or run an agent against it.
Sections:
- **Contributing** — how to contribute, filing good issues, readiness
labels, why feature work goes through a spec PR, building from source,
the Oz + SME review flow, what to do when a PR is stuck, becoming a
collaborator.
- **Using an agent on this repo** — bringing your own agent, how to get
Oz to implement an issue for you, cost, the quality bar for
agent-generated PRs, training data.
- **What's open source and what isn't** — straightforward answers about
which parts of Warp live in this repo (the client) and which don't (the
server, Drive backend, Oz), and what running locally without the cloud
looks like.
- **Licensing** — why we chose AGPL for the app and MIT for the UI
framework crates, enterprise use, the CLA, forking.
- **Help and security** — where to ask questions, how to report security
issues.
Most of the substance is already implied by `README.md`,
`CONTRIBUTING.md`, `SECURITY.md`, and the licenses; the FAQ pulls those
answers into one skimmable place and answers a few questions that aren't
covered elsewhere (e.g. "is Warp fully open source", "can I get Oz to
implement my issue", "why AGPL").
## Testing
Documentation-only change. Verified the rendered Markdown locally and
that all in-repo links resolve.
## Changelog Entries for Stable
<!-- Docs-only addition; no changelog entry. -->
---------
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
Restore orchestration event delivery on the client after a Warp restart
so that a parent conversation continues to receive lifecycle events and
inbox messages from its children — including terminal events that
arrived while Warp was not running.
See the full design in `specs/replay-agent-events-on-restore/PRODUCT.md`
and `specs/replay-agent-events-on-restore/TECH.md`.
This is a re-land of warpdotdev/warp-internal#24999, which was reverted
in warpdotdev/warp-internal#25055 due to a CI race. This version fixes
the test compilation issue (missing fields in `AmbientAgentTask` struct
literal in `conversation_ended_tombstone_view_tests.rs`).
### What
- Persists the per-conversation event cursor across restarts.
- Adds `last_event_sequence: Option<i64>` to `AgentConversationData`
(SQLite) and `AIConversation`.
- New `BlocklistAIHistoryModel::update_event_sequence` helper writes the
cursor through `write_updated_conversation_state` after each event
batch.
- Also persists the cursor to the server (fire-and-forget) so driver /
cloud restarts can resume without local SQLite state.
- Restores `OrchestrationEventPoller.watched_run_ids` and re-establishes
event delivery on `BlocklistAIHistoryEvent::RestoredConversations`.
- New `on_restored_conversations` handler issues `GET
/agent/runs/{run_id}` for each restored parent and uses the response
inline `children` and `last_event_sequence` to populate watched run ids
and merge the cursor (`max(SQLite, server)`).
- Fetch failures retry with exponential backoff (1s, 2s, 5s, 10s capped)
keyed off a per-conversation `restore_fetch_failures` counter; reset on
success and on conversation removal.
- Gated on `OrchestrationV2`. Shared-session viewers and conversations
without children are skipped.
- `Success` parents resume delivery immediately; `InProgress` parents
defer to the existing `on_conversation_status_updated` path.
- Restores V1 lifecycle subscriptions on restart by extending the
existing `RestoredConversations` handler in `OrchestrationEventService`
to re-register `lifecycle_subscription_routes` for restored child
conversations whose parents are present locally.
### Why
After a Warp restart, parent conversations were silently receiving no
further events from children. The `event_cursor` in
`OrchestrationEventPoller` was always initialized to 0, so even if
delivery had resumed, every event since the start of the conversation
would have replayed and produced duplicate messages. V1 lifecycle
subscription routes were also not restored, so V1 parents missed child
status transitions.
## Testing
- Added unit tests in
`app/src/ai/blocklist/orchestration_event_poller_tests.rs` covering:
cursor merge from server vs SQLite, retry on `get_ambient_agent_task`
failure, V2 gating, shared-session-viewer exclusion, cleanup on delete,
and `last_event_sequence` round-trip through
`AIConversation::new_restored`.
- Added unit test coverage in
`app/src/ai/blocklist/orchestration_events_tests.rs` for V1 lifecycle
re-registration on restore.
- Manual verification per
`specs/replay-agent-events-on-restore/TECH.md`.
## Server API dependencies
- [x] Does this change rely on a [new server
API](https://www.notion.so/warpdev/How-to-add-a-new-full-stack-feature-8412cede405a4ec194b32bdd4b951035?pvs=4#04da1e6a493542d68b3e998c7d339640)?
- [x] If so, is the use of this API restricted to client channels that
rely on the staging server (e.g. WarpDev)?
The companion server change adds:
- `last_event_sequence` on `Task` (`ai_tasks` column), surfaced inline
on `GET /agent/runs/:run_id`.
- `PATCH /agent/runs/:run_id/event-sequence` for client cursor writes.
- `children` inline on the `GET /agent/runs/:run_id` response.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
Co-Authored-By: Oz <oz-agent@warp.dev>
---------
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
Currently our preview remote server implementation could crash if we
tried to send a telemetry event because we never initialized our
telemetry context provider
We will migrate this soon to an actual telemetry provider once we have
auth syncing. But for now, we are going to use a noop telemetry provider
## Testing
Tested locally to confirm this is no longer panicking
Updated image source in README to use GitHub link.
## Description
<!-- Please remember to add your design buddy onto the PR for review, if
it contains any UI changes! -->
## Testing
<!--
How did you test this change? What automated tests did you add? If you
didn't add any new tests, what's your justification for not adding any?
If you're not sure whether you should add a test, check our testing
policy:
https://www.notion.so/warpdev/How-We-Code-at-Warp-257fe43d556e4b3c8dfd42f70004cc72#1f97825450504baa9c5fd87a737daa09
-->
## Server API dependencies
<!-- You may remove this section if your PR does not have any server
dependencies. -->
- [ ] Is this change necessary to make the client compatible with a
desired [server API breaking
change](https://www.notion.so/warpdev/How-to-safely-introduce-server-API-breaking-changes-0aa805ff5d5d41fd8834f3c95caba0b4?pvs=4#d55ecf8aea3449949d3c33b0e67f6800)?
- [ ] Does this change rely on a [new server
API](https://www.notion.so/warpdev/How-to-add-a-new-full-stack-feature-8412cede405a4ec194b32bdd4b951035?pvs=4#04da1e6a493542d68b3e998c7d339640)?
- [ ] If so, is the use of this API restricted to client channels that
rely on the staging server (e.g. WarpDev)?
- [ ] Is this change enabling the use of a server API on client channels
that rely on the production server (e.g. WarpStable)?
- [ ] If so, has the new server API been stable on production for at
least one server release cycle? See
[here](https://www.notion.so/warpdev/How-to-add-a-new-full-stack-feature-8412cede405a4ec194b32bdd4b951035?pvs=4#73b202f939834b97ab1fbdf7fc82cd53)
for more details.
## Agent Mode
- [ ] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
## Changelog Entries for Stable
<!--
The entries below will be used when constructing a soft-copy of the
stable release changelog. Leave blank or remove the lines if no entry in
the stable changelog is needed. Entries should be on the same line,
without the `{{` `}}` brackets. You can use multiple lines, even of the
same type. The valid suffixes are:
* NEW-FEATURE: for new, relatively sizable features. Features listed
here will likely have docs / social media posts / marketing launches
associated with them, so use sparingly.
* IMPROVEMENT: for new functionality of existing features.
* BUG-FIX: for fixes related to known bugs or regressions.
* IMAGE: the image specified by the URL (hosted on GCP) will be added to
Dev & Preview releases. For Stable releases, see the pinned doc in the
#release Slack channel.
* OZ: Oz-related updates. Use `CHANGELOG-OZ`. At most 4 Oz updates are
shown in-app per release.
-->
CHANGELOG-NEW-FEATURE: {{text goes here...}}
CHANGELOG-IMPROVEMENT: {{text goes here...}}
CHANGELOG-BUG-FIX: {{text goes here...}}
CHANGELOG-BUG-FIX: {{more text goes here...}}
CHANGELOG-IMAGE: {{GCP-hosted URL goes here...}}
CHANGELOG-OZ: {{text goes here...}}
## Description
Disables the commit message editor while the async commit (and optional
push / create-PR chain) is in flight, so the user can't edit the message
text mid-operation.
Fixes APP-4260.
## Testing
Manually verified the editor is locked once "Confirm" is pressed and
stays locked through the async commit/push/PR flow.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
CHANGELOG-BUG-FIX: Disabled the commit message editor while a git commit
is being performed in the git operations dialog.
[Conversation](https://staging.warp.dev/conversation/11795cb8-3dcc-4bcd-90c9-53f974585fe6)
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
### Motivation
File-based stdio MCP servers spawned from a project's `.mcp.json` (e.g. `pnpm run mcp:foo`, or anything using `./tooling_scripts/...`) fail with:
```
Transport creation error: No such file or directory (os error 2)
```
Root cause: when the user's `.mcp.json` doesn't include a `working_directory`, Warp's spawner inherits whatever cwd Warp was launched from rather than the directory the config was discovered in. Two failure modes share this same root cause:
- **Repo-relative commands/args** (e.g. `./tooling_scripts/foo`, `node ./src/server.js`) can't be resolved from outside the repo, so `execvp` returns `ENOENT`.
- **Workspace-aware launchers** like `pnpm`/`npm`/`yarn` walk up from cwd looking for `package.json` (and workspace manifests). When cwd isn't inside the repo, they bail out before launching the requested script — surfacing as `ENOENT` from the spawner's perspective.
`working_directory` is a Warp/VS-Code-style extension; the canonical Anthropic/Cursor MCP schemas don't include it, so most `.mcp.json` files in the wild don't set it.
### Implementation
- New helper `FileBasedMCPManager::spawn_root_for_installation(uuid)` returning the discovery root for any file-based install: the repo root for project-scoped configs, the home directory for global configs (Warp and third-party). Returns `None` for non-file-based installs (e.g. cloud-templated ones), leaving them unaffected. Global Warp installs are remapped from `~/.warp/` (Warp internal state) to `~` so all global installs share a consistent cwd.
- In `TemplatableMCPServerManager::spawn_server_impl`, default `cli_server.cwd_parameter` from this helper when unset. Single funnel — covers both auto-spawn and the manual UI opt-in path. User-supplied `working_directory` always wins.
- ENOENT-aware logging at the spawn site: when `TokioChildProcess::spawn()` fails with `NotFound`, the MCP log file now spells out the server name, the missing executable, the cwd we used, and a hint pointing the user at `working_directory`. The user-surfaced error string is unchanged.
- Documented the new defaulting behavior and `working_directory` override in `resources/bundled/skills/add-mcp-server/SKILL.md`.
## Testing
Verified spawn-site behavior manually. Demo [here](https://www.loom.com/share/ec01d98ae9114433b8ae87f5f17adfd4)!
- Added `test_parse_cli_server_preserves_explicit_working_directory` in `mod_test.rs` to lock in that an explicitly-set `working_directory` round-trips through parsing and won't be clobbered by the new defaulting logic.
- Skipped a unit test for the new helper itself — it's a thin lookup over `file_based_servers_by_root` and the sorted-pick policy is straightforward enough to validate manually.
- Spawn-site behavior (cwd actually applied, ENOENT log emission) verified manually against a `pnpm`\-based repro.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
## Changelog Entries for Stable
CHANGELOG-BUG-FIX: Project-scoped file-based MCP servers now spawn from the repo root by default (and global ones from `~`), so configs with relative commands/args (and workspace launchers like `pnpm`/`npm`) work without an explicit `working_directory`.
## Description
Moves the "Discard all" menu item to the last position in
`header_menu_items_new`, so it appears after the AI context and comment
items. This matches the intended UX ordering from
[WAR-7381](https://linear.app/warpdotdev/issue/WAR-7381/discard-all-should-be-the-last-item-in-the-list).
## Testing
Manually verified the ordering logic. No new tests needed — this is a
pure reordering of existing menu items with no behavioral changes.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
Adds contextual tooltips to disabled git operation buttons so users
understand why they can't click them. Tooltips are intentionally limited
to **disabled states only** — enabled buttons don't get tooltips since
their labels are self-explanatory.
**Changes:**
- Code review header: "No changes to commit" on the disabled Commit
button; "No git actions available" on the disabled chevron
- Commit dialog: "Enter a commit message" on the disabled Confirm button
(only shown once file changes have loaded — silent during the async load
window)
- Bug fix: the PR #N button in the header was staying greyed out after
transitioning from a disabled Commit mode, because `ViewPr` mode never
called `set_disabled(false)`
Linear:
https://linear.app/warpdotdev/issue/APP-4261/git-buttons-should-all-have-tooltips
Warp conversation:
https://staging.warp.dev/conversation/27f5811f-22ea-4c4b-8d8f-47ff48a5b12b
Loom: https://www.loom.com/share/932cfb22039c4566bcc7a7343b624d81
## Testing
Manually verified:
- Commit button with no changes shows "No changes to commit" on hover
- Chevron with no changes shows "No git actions available" on hover
- Commit dialog Confirm button shows "Enter a commit message" once files
load but message is empty; no tooltip shown during async load
- PR #N button is no longer greyed out after committing all changes
No new automated tests added — these are tooltip strings on existing
button state logic that is already exercised by existing tests.
## Server API dependencies
N/A — client-only change.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
## Changelog Entries for Stable
CHANGELOG-IMPROVEMENT: Git operation buttons now show tooltips
explaining why they're disabled (e.g. "No changes to commit", "Enter a
commit message").
Co-Authored-By: Oz <oz-agent@warp.dev>
---------
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
A couple issues that needed fixing:
* Using `--all-features` and `--all-targets` causes us to try to build
the first-party binaries with embedded configuration, which isn't
available from this repository. To unblock CI, we'll only run clippy on
the default feature set for right now.
* Similarly, testing compilation with release configuration was trying
to build the `dev` channel; this switches that over to the `oss`
channel.
## Description
The local `Review Pull Request` workflow in this repo has been failing
on every `pull_request_target` event with `startup_failure` (no jobs
created) for newly opened PRs. Recent runs that hit this:
- https://github.com/warpdotdev/warp/actions/runs/25059789050
- https://github.com/warpdotdev/warp/actions/runs/25059784082
- https://github.com/warpdotdev/warp/actions/runs/25059568488
### Root cause
`.github/workflows/review-pull-request.yml` declares a `focus` input on
its own `workflow_call` interface and forwards it to the upstream
reusable workflow at
`warpdotdev/oz-for-oss/.github/workflows/review-pull-request.yml@main`.
That upstream workflow's `workflow_call` interface no longer declares
`focus` — it was removed in oz-for-oss commit
[`757b052`](https://github.com/warpdotdev/oz-for-oss/commit/757b052) (PR
#393, "feat(review): allow non-collaborator /oz-review and cap at 3 per
PR"). When the local job tries to forward `focus:` in its `with:` block,
GitHub fails workflow validation before any job is created, which
surfaces as `startup_failure`.
### What this PR changes
Drops every reference to `focus` from the local caller so the contract
matches the upstream `workflow_call` again:
- Removes the `focus` input from `workflow_call.inputs`
- Removes `INPUT_FOCUS` from the `resolve` step's `env`
- Removes the `focus = os.environ.get("INPUT_FOCUS", "")` read and the
heredoc-style `focus<<__EOF__` write to `GITHUB_OUTPUT`
- Removes `focus` from the `resolve` job's `outputs:`
- Removes `focus: ${{ needs.resolve.outputs.focus }}` from the
`review_pr` reusable-workflow `with:`
The forwarded inputs are now `pr_number`, `trigger_source`, `requester`,
and `comment_id`, matching the upstream interface.
### Note on `enforce-pr-issue-state.yml`
While debugging, I confirmed `enforce-pr-issue-state.yml` is
`workflow_call`-only and is not invoked anywhere in this repo (it has
zero historical runs), unlike in `oz-for-oss` where `pr-hooks.yml`
orchestrates enforcement before reviews. That gap is independent of this
fix — `review-pull-request.yml` here listens directly to
`pull_request_target` and does not depend on enforcement output. If we
want enforcement to gate PR reviews on this repo too, that's a follow-up
(either add a `pr-hooks.yml` orchestrator or wire
`enforce-pr-issue-state.yml` to listen to `pull_request_target` directly
and have `review-pull-request.yml` `needs:` it).
## Testing
- `python3 -c "import yaml; yaml.safe_load(...)"` on the modified
workflow to confirm the YAML still parses.
- Diff-checked that the local `with:` block matches the inputs declared
by the upstream `workflow_call` at
`warpdotdev/oz-for-oss/.github/workflows/review-pull-request.yml@main`.
- After this merges, the next `pull_request_target` event on a non-draft
PR should produce a `Review Pull Request` run that actually creates the
`resolve` and `review_pr` jobs instead of failing at startup.
## Server API dependencies
N/A — CI workflow change only.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
_Conversation:
https://staging.warp.dev/conversation/dd8c9b9a-256b-4c79-abc2-cb513f7236b5_
## Changelog Entries for Stable
Co-authored-by: Oz <oz-agent@warp.dev>
## Description
The reusable workflows under
[`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/tree/main/.github/workflows)
declare their Warp API key secret as `OSS_WARP_API_KEY`, but the local
caller workflows in this repo were forwarding it as `WARP_API_KEY`.
Because the name being passed didn't match the name declared by
`workflow_call`, the required secret was effectively missing and an
undeclared secret was being passed instead, which caused
`startup_failure` on every invocation.
Example failure:
https://github.com/warpdotdev/warp/actions/runs/25058665906 (Triage New
Issues (Local), `startup_failure`).
This PR renames the forwarded secret to `OSS_WARP_API_KEY:` in all local
adapter workflows so the names match what the reusable workflows
declare. The underlying secret value is still pulled from
`secrets.OSS_WARP_API_KEY` in this repo, so no repo secret changes are
needed.
Affected workflows:
- `.github/workflows/create-implementation-from-issue-local.yml`
- `.github/workflows/create-spec-from-issue-local.yml`
- `.github/workflows/enforce-pr-issue-state.yml`
- `.github/workflows/respond-to-pr-comment-local.yml`
- `.github/workflows/respond-to-triaged-issue-comment-local.yml`
- `.github/workflows/review-pull-request.yml`
- `.github/workflows/triage-new-issues-local.yml`
- `.github/workflows/trigger-implementation-on-plan-approved-local.yml`
- `.github/workflows/update-dedupe-local.yml`
- `.github/workflows/update-pr-review-local.yml`
- `.github/workflows/update-triage-local.yml`
- `.github/workflows/verify-pr-comment-local.yml`
## Testing
Manual review of the rename. After merge, re-run the failing `Triage New
Issues (Local)` workflow to confirm it no longer hits `startup_failure`
due to a missing required secret.
## Server API dependencies
N/A — CI workflow change only.
## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
_Conversation:
https://staging.warp.dev/conversation/fbace74a-9da2-445f-8486-e5a5907dce57_
_Run:
https://oz.staging.warp.dev/runs/019dd47c-42e0-7072-8206-e6be4df5cde7_
_This PR was generated with [Oz](https://warp.dev/oz)._
Co-authored-by: Oz Agent <oz-agent@warp.dev>
