paperclip/docs/guides/board-operator/execution-workspaces-and-runtime-services.md at local

Files

T

Dotta e89076148a [codex] Improve workspace runtime and navigation ergonomics (#3680 )

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - That operator experience depends not just on issue chat, but also on
how workspaces, inbox groups, and navigation state behave over
long-running sessions
> - The current branch included a separate cluster of workspace-runtime
controls, inbox grouping, sidebar ordering, and worktree lifecycle fixes
> - Those changes cross server, shared contracts, database state, and UI
navigation, but they still form one coherent operator workflow area
> - This pull request isolates the workspace/runtime and navigation
ergonomics work into one standalone branch
> - The benefit is better workspace recovery and navigation persistence
without forcing reviewers through the unrelated issue-detail/chat work

## What Changed

- Improved execution workspace and project workspace controls, request
wiring, layout, and JSON editor ergonomics
- Hardened linked worktree reuse/startup behavior and documented the
`worktree repair` flow for recovering linked worktrees safely
- Added inbox workspace grouping, mobile collapse, archive undo,
keyboard navigation, shared group-header styling, and persisted
collapsed-group behavior
- Added persistent sidebar order preferences with the supporting DB
migration, shared/server contracts, routes, services, hooks, and UI
integration
- Scoped issue-list preferences by context and added targeted UI/server
tests for workspace controls, inbox behavior, sidebar preferences, and
worktree validation

## Verification

- `pnpm vitest run
server/src/__tests__/sidebar-preferences-routes.test.ts
ui/src/pages/Inbox.test.tsx
ui/src/components/ProjectWorkspaceSummaryCard.test.tsx
ui/src/components/WorkspaceRuntimeControls.test.tsx
ui/src/api/workspace-runtime-control.test.ts`
- `server/src/__tests__/workspace-runtime.test.ts` was attempted, but
the embedded Postgres suite self-skipped/hung on this host after
reporting an init-script issue, so it is not counted as a local pass
here

## Risks

- Medium: this branch includes migration-backed preference storage plus
worktree/runtime behavior, so merge review should pay attention to state
persistence and worktree recovery semantics
- The sidebar preference migration is standalone, but it should still be
watched for conflicts if another migration lands first

## Model Used

- OpenAI Codex coding agent (GPT-5-class runtime in Codex CLI; exact
deployed model ID is not exposed in this environment), reasoning
enabled, tool use and local code execution enabled

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-04-14 12:57:11 -05:00

3.9 KiB

Raw Permalink Blame History

title, summary

title	summary
Execution Workspaces And Runtime Services	How project runtime configuration, execution workspaces, and issue runs fit together

This guide documents the intended runtime model for projects, execution workspaces, and issue runs in Paperclip.

Paperclip now presents this as a workspace-command model:

Services are long-running commands that stay supervised.
Jobs are one-shot commands that run once and exit.
Raw runtime JSON is still available for advanced config, but it is no longer the primary mental model.

Project runtime configuration

You can define how to run a project on the project workspace itself.

Project workspace runtime config describes the services and jobs available for that project checkout.
This is the default runtime configuration that child execution workspaces may inherit.
Defining the config does not start anything by itself.

Manual runtime control

Workspace commands are manually controlled from the UI.

Project workspace services are started and stopped from the project workspace UI, and project jobs can be run on demand there.
Execution workspace services are started and stopped from the execution workspace UI, and execution-workspace jobs can be run on demand there.
Paperclip does not automatically start or stop these workspace services as part of issue execution.
Paperclip also does not automatically restart workspace services on server boot.

Execution workspace inheritance

Execution workspaces isolate code and runtime state from the project primary workspace.

An isolated execution workspace has its own checkout path, branch, and local runtime instance.
The runtime configuration may inherit from the linked project workspace by default.
The execution workspace may override that runtime configuration with its own workspace-specific settings.
The inherited configuration answers "which commands exist and how to run them", but any running service process is still specific to that execution workspace.

Issues and execution workspaces

Issues are attached to execution workspace behavior, not to automatic runtime management.

An issue may create a new execution workspace when you choose an isolated workspace mode.
An issue may reuse an existing execution workspace when you choose reuse.
Multiple issues may intentionally share one execution workspace so they can work against the same branch and running runtime services.
Assigning or running an issue does not automatically start or stop workspace services for that workspace.

Execution workspace lifecycle

Execution workspaces are durable until a human closes them.

The UI can archive an execution workspace.
Closing an execution workspace stops its runtime services and cleans up its workspace artifacts when allowed.
Shared workspaces that point at the project primary checkout are treated more conservatively during cleanup than disposable isolated workspaces.

Resolved workspace logic during heartbeat runs

Heartbeat still resolves a workspace for the run, but that is about code location and session continuity, not runtime-service control.

Heartbeat resolves a base workspace for the run.
Paperclip realizes the effective execution workspace, including creating or reusing a worktree when needed.
Paperclip persists execution-workspace metadata such as paths, refs, and provisioning settings.
Heartbeat passes the resolved code workspace to the agent run.
Workspace runtime services remain manual UI-managed controls rather than automatic heartbeat-managed services.

Current implementation guarantees

With the current implementation:

Project workspace command config is the fallback for execution workspace UI controls.
Execution workspace runtime overrides are stored on the execution workspace.
Heartbeat runs do not auto-start workspace services.
Server startup does not auto-restart workspace services.

3.9 KiB Raw Permalink Blame History