[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>

doc/DEVELOPING.md

@@ -239,7 +239,7 @@ paperclipai worktree init --force
 Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install:
 
 ```sh
-cd ~/.paperclip/worktrees/PAP-884-ai-commits-component
+cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
 pnpm paperclipai worktree init --force --seed-mode minimal \
   --name PAP-884-ai-commits-component \
   --from-config ~/.paperclip/instances/default/config.json
@@ -247,6 +247,33 @@ pnpm paperclipai worktree init --force --seed-mode minimal \
 
 That rewrites the worktree-local `.paperclip/config.json` + `.paperclip/.env`, recreates the isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`, and preserves the git worktree contents themselves.
 
+For an already-created worktree where you want the CLI to decide whether to rebuild missing worktree metadata or just reseed the isolated DB, use `worktree repair`.
+
+**`pnpm paperclipai worktree repair [options]`** — Repair the current linked worktree by default, or create/repair a named linked worktree under `.paperclip/worktrees/` when `--branch` is provided. The command never targets the primary checkout unless you explicitly pass `--branch`.
+
+| Option | Description |
+|---|---|
+| `--branch <name>` | Existing branch/worktree selector to repair, or a branch name to create under `.paperclip/worktrees` |
+| `--home <path>` | Home root for worktree instances (default: `~/.paperclip-worktrees`) |
+| `--from-config <path>` | Source config.json to seed from |
+| `--from-data-dir <path>` | Source `PAPERCLIP_HOME` used when deriving the source config |
+| `--from-instance <id>` | Source instance id when deriving the source config (default: `default`) |
+| `--seed-mode <mode>` | Seed profile: `minimal` or `full` (default: `minimal`) |
+| `--no-seed` | Repair metadata only when bootstrapping a missing worktree config |
+| `--allow-live-target` | Override the guard that requires the target worktree DB to be stopped first |
+
+Examples:
+
+```sh
+# From inside a linked worktree, rebuild missing .paperclip metadata and reseed it from the default instance.
+cd /path/to/paperclip/.paperclip/worktrees/PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
+pnpm paperclipai worktree repair
+
+# From the primary checkout, create or repair a linked worktree for a branch under .paperclip/worktrees/.
+cd /path/to/paperclip
+pnpm paperclipai worktree repair --branch PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
+```
+
 For an already-created worktree where you want to keep the existing repo-local config/env and only overwrite the isolated database, use `worktree reseed` instead. Stop the target worktree's Paperclip server first so the command can replace the DB safely.
 
 **`pnpm paperclipai worktree reseed [options]`** — Re-seed an existing worktree-local instance from another Paperclip instance or worktree while preserving the target worktree's current config, ports, and instance identity.

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

@@ -5,22 +5,28 @@ summary: How project runtime configuration, execution workspaces, and issue runs
 
 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 how to run services for that project checkout.
+- 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
 
-Runtime services are manually controlled from the UI.
+Workspace commands are manually controlled from the UI.
 
-- Project workspace runtime services are started and stopped from the project workspace UI.
-- Execution workspace runtime services are started and stopped from the execution workspace UI.
-- Paperclip does not automatically start or stop these runtime services as part of issue execution.
-- Paperclip also does not automatically restart workspace runtime services on server boot.
+- 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
 
@@ -29,7 +35,7 @@ Execution workspaces isolate code and runtime state from the project primary wor
 - 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 "how to run the service", but the running process is still specific to that execution workspace.
+- 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
 
@@ -38,7 +44,7 @@ Issues are attached to execution workspace behavior, not to automatic runtime ma
 - 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 runtime services for that workspace.
+- Assigning or running an issue does not automatically start or stop workspace services for that workspace.
 
 ## Execution workspace lifecycle
 
@@ -62,7 +68,7 @@ Heartbeat still resolves a workspace for the run, but that is about code locatio
 
 With the current implementation:
 
-- Project workspace runtime config is the fallback for execution workspace UI controls.
+- 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 runtime services.
-- Server startup does not auto-restart workspace runtime services.
+- Heartbeat runs do not auto-start workspace services.
+- Server startup does not auto-restart workspace services.

packages/db/src/migrations/0056_spooky_ultragirl.sql

@@ -0,0 +1,22 @@
+CREATE TABLE "company_user_sidebar_preferences" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"project_order" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "user_sidebar_preferences" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"company_order" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "company_user_sidebar_preferences" ADD CONSTRAINT "company_user_sidebar_preferences_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "company_user_sidebar_preferences_company_idx" ON "company_user_sidebar_preferences" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "company_user_sidebar_preferences_user_idx" ON "company_user_sidebar_preferences" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "company_user_sidebar_preferences_company_user_uq" ON "company_user_sidebar_preferences" USING btree ("company_id","user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "user_sidebar_preferences_user_uq" ON "user_sidebar_preferences" USING btree ("user_id");

packages/db/src/migrations/meta/_journal.json

@@ -393,6 +393,13 @@
       "when": 1775825256196,
       "tag": "0055_kind_weapon_omega",
       "breakpoints": true
+    },
+    {
+      "idx": 56,
+      "version": "7",
+      "when": 1776084034244,
+      "tag": "0056_spooky_ultragirl",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/company_user_sidebar_preferences.ts

@@ -0,0 +1,22 @@
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+
+export const companyUserSidebarPreferences = pgTable(
+  "company_user_sidebar_preferences",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    projectOrder: jsonb("project_order").$type<string[]>().notNull().default([]),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyIdx: index("company_user_sidebar_preferences_company_idx").on(table.companyId),
+    userIdx: index("company_user_sidebar_preferences_user_idx").on(table.userId),
+    companyUserUq: uniqueIndex("company_user_sidebar_preferences_company_user_uq").on(
+      table.companyId,
+      table.userId,
+    ),
+  }),
+);

packages/db/src/schema/index.ts

@@ -3,10 +3,12 @@ export { companyLogos } from "./company_logos.js";
 export { authUsers, authSessions, authAccounts, authVerifications } from "./auth.js";
 export { instanceSettings } from "./instance_settings.js";
 export { instanceUserRoles } from "./instance_user_roles.js";
+export { userSidebarPreferences } from "./user_sidebar_preferences.js";
 export { agents } from "./agents.js";
 export { boardApiKeys } from "./board_api_keys.js";
 export { cliAuthChallenges } from "./cli_auth_challenges.js";
 export { companyMemberships } from "./company_memberships.js";
+export { companyUserSidebarPreferences } from "./company_user_sidebar_preferences.js";
 export { principalPermissionGrants } from "./principal_permission_grants.js";
 export { invites } from "./invites.js";
 export { joinRequests } from "./join_requests.js";

packages/db/src/schema/user_sidebar_preferences.ts

@@ -0,0 +1,15 @@
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const userSidebarPreferences = pgTable(
+  "user_sidebar_preferences",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: text("user_id").notNull(),
+    companyOrder: jsonb("company_order").$type<string[]>().notNull().default([]),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    userUq: uniqueIndex("user_sidebar_preferences_user_uq").on(table.userId),
+  }),
+);

packages/shared/src/api.ts

@@ -13,6 +13,7 @@ export const API = {
   activity: `${API_PREFIX}/activity`,
   dashboard: `${API_PREFIX}/dashboard`,
   sidebarBadges: `${API_PREFIX}/sidebar-badges`,
+  sidebarPreferences: `${API_PREFIX}/sidebar-preferences`,
   invites: `${API_PREFIX}/invites`,
   joinRequests: `${API_PREFIX}/join-requests`,
   members: `${API_PREFIX}/members`,

packages/shared/src/index.ts

@@ -232,7 +232,11 @@ export type {
   ExecutionWorkspaceCloseReadiness,
   ExecutionWorkspaceCloseReadinessState,
   ProjectWorkspaceRuntimeConfig,
+  WorkspaceCommandDefinition,
+  WorkspaceCommandKind,
+  WorkspaceRuntimeControlTarget,
   WorkspaceRuntimeService,
+  WorkspaceRuntimeServiceStateMap,
   WorkspaceOperation,
   WorkspaceOperationPhase,
   WorkspaceOperationStatus,
@@ -301,6 +305,7 @@ export type {
   DashboardSummary,
   ActivityEvent,
   SidebarBadges,
+  SidebarOrderPreference,
   InboxDismissal,
   CompanyMembership,
   PrincipalPermissionGrant,
@@ -374,6 +379,21 @@ export type {
   ProviderQuotaResult,
 } from "./types/index.js";
 
+export {
+  sidebarOrderPreferenceSchema,
+  upsertSidebarOrderPreferenceSchema,
+  type UpsertSidebarOrderPreference,
+} from "./validators/sidebar-preferences.js";
+
+export { workspaceRuntimeControlTargetSchema } from "./validators/execution-workspace.js";
+export {
+  findWorkspaceCommandDefinition,
+  listWorkspaceCommandDefinitions,
+  listWorkspaceServiceCommandDefinitions,
+  matchWorkspaceRuntimeServiceToCommand,
+  scoreWorkspaceRuntimeServiceMatch,
+} from "./workspace-commands.js";
+
 export {
   DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE,
   FEEDBACK_TARGET_TYPES,

packages/shared/src/types/index.ts

@@ -71,7 +71,11 @@ export type {
   ExecutionWorkspaceCloseReadiness,
   ExecutionWorkspaceCloseReadinessState,
   ProjectWorkspaceRuntimeConfig,
+  WorkspaceCommandDefinition,
+  WorkspaceCommandKind,
+  WorkspaceRuntimeControlTarget,
   WorkspaceRuntimeService,
+  WorkspaceRuntimeServiceStateMap,
   WorkspaceRuntimeDesiredState,
   ExecutionWorkspaceStrategyType,
   ExecutionWorkspaceMode,
@@ -165,6 +169,7 @@ export type { LiveEvent } from "./live.js";
 export type { DashboardSummary } from "./dashboard.js";
 export type { ActivityEvent } from "./activity.js";
 export type { SidebarBadges } from "./sidebar-badges.js";
+export type { SidebarOrderPreference } from "./sidebar-preferences.js";
 export type { InboxDismissal } from "./inbox-dismissal.js";
 export type {
   CompanyMembership,

packages/shared/src/types/sidebar-preferences.ts

@@ -0,0 +1,4 @@
+export interface SidebarOrderPreference {
+  orderedIds: string[];
+  updatedAt: Date | null;
+}

packages/shared/src/types/workspace-runtime.ts

@@ -46,6 +46,27 @@ export type ExecutionWorkspaceCloseActionKind =
   | "remove_local_directory";
 
 export type WorkspaceRuntimeDesiredState = "running" | "stopped";
+export type WorkspaceRuntimeServiceStateMap = Record<string, WorkspaceRuntimeDesiredState>;
+export type WorkspaceCommandKind = "service" | "job";
+
+export interface WorkspaceCommandSource {
+  type: "paperclip";
+  key: "commands" | "services" | "jobs";
+  index: number;
+}
+
+export interface WorkspaceCommandDefinition {
+  id: string;
+  name: string;
+  kind: WorkspaceCommandKind;
+  command: string | null;
+  cwd: string | null;
+  lifecycle: "shared" | "ephemeral" | null;
+  serviceIndex: number | null;
+  disabledReason: string | null;
+  rawConfig: Record<string, unknown>;
+  source: WorkspaceCommandSource;
+}
 
 export interface ExecutionWorkspaceStrategy {
   type: ExecutionWorkspaceStrategyType;
@@ -62,11 +83,19 @@ export interface ExecutionWorkspaceConfig {
   cleanupCommand: string | null;
   workspaceRuntime: Record<string, unknown> | null;
   desiredState: WorkspaceRuntimeDesiredState | null;
+  serviceStates?: WorkspaceRuntimeServiceStateMap | null;
 }
 
 export interface ProjectWorkspaceRuntimeConfig {
   workspaceRuntime: Record<string, unknown> | null;
   desiredState: WorkspaceRuntimeDesiredState | null;
+  serviceStates?: WorkspaceRuntimeServiceStateMap | null;
+}
+
+export interface WorkspaceRuntimeControlTarget {
+  workspaceCommandId?: string | null;
+  runtimeServiceId?: string | null;
+  serviceIndex?: number | null;
 }
 
 export interface ExecutionWorkspaceCloseAction {
@@ -187,6 +216,7 @@ export interface WorkspaceRuntimeService {
   stoppedAt: Date | null;
   stopPolicy: Record<string, unknown> | null;
   healthStatus: "unknown" | "healthy" | "unhealthy";
+  configIndex?: number | null;
   createdAt: Date;
   updatedAt: Date;
 }

packages/shared/src/validators/execution-workspace.ts

@@ -14,6 +14,13 @@ export const executionWorkspaceConfigSchema = z.object({
   cleanupCommand: z.string().optional().nullable(),
   workspaceRuntime: z.record(z.unknown()).optional().nullable(),
   desiredState: z.enum(["running", "stopped"]).optional().nullable(),
+  serviceStates: z.record(z.enum(["running", "stopped"])).optional().nullable(),
+}).strict();
+
+export const workspaceRuntimeControlTargetSchema = z.object({
+  workspaceCommandId: z.string().min(1).optional().nullable(),
+  runtimeServiceId: z.string().uuid().optional().nullable(),
+  serviceIndex: z.number().int().nonnegative().optional().nullable(),
 }).strict();
 
 export const executionWorkspaceCloseReadinessStateSchema = z.enum([
@@ -88,6 +95,7 @@ export const workspaceRuntimeServiceSchema = z.object({
   stoppedAt: z.coerce.date().nullable(),
   stopPolicy: z.record(z.unknown()).nullable(),
   healthStatus: z.enum(["unknown", "healthy", "unhealthy"]),
+  configIndex: z.number().int().nonnegative().nullable().optional(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 }).strict();

packages/shared/src/validators/index.ts

@@ -32,6 +32,11 @@ export {
   upsertIssueFeedbackVoteSchema,
   type UpsertIssueFeedbackVote,
 } from "./feedback.js";
+export {
+  sidebarOrderPreferenceSchema,
+  upsertSidebarOrderPreferenceSchema,
+  type UpsertSidebarOrderPreference,
+} from "./sidebar-preferences.js";
 export {
   companySkillSourceTypeSchema,
   companySkillTrustLevelSchema,

packages/shared/src/validators/project.ts

@@ -31,6 +31,7 @@ export const projectExecutionWorkspacePolicySchema = z
 export const projectWorkspaceRuntimeConfigSchema = z.object({
   workspaceRuntime: z.record(z.unknown()).optional().nullable(),
   desiredState: z.enum(["running", "stopped"]).optional().nullable(),
+  serviceStates: z.record(z.enum(["running", "stopped"])).optional().nullable(),
 }).strict();
 
 const projectWorkspaceSourceTypeSchema = z.enum(["local_path", "git_repo", "remote_managed", "non_git_path"]);

packages/shared/src/validators/sidebar-preferences.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+const sidebarOrderedIdSchema = z.string().uuid();
+
+export const sidebarOrderPreferenceSchema = z.object({
+  orderedIds: z.array(sidebarOrderedIdSchema),
+  updatedAt: z.coerce.date().nullable(),
+});
+
+export const upsertSidebarOrderPreferenceSchema = z.object({
+  orderedIds: z.array(sidebarOrderedIdSchema),
+});
+
+export type UpsertSidebarOrderPreference = z.infer<typeof upsertSidebarOrderPreferenceSchema>;

packages/shared/src/workspace-commands.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import {
+  findWorkspaceCommandDefinition,
+  listWorkspaceCommandDefinitions,
+  matchWorkspaceRuntimeServiceToCommand,
+} from "./workspace-commands.js";
+
+describe("workspace command helpers", () => {
+  it("derives service and job commands from command-first runtime config", () => {
+    const commands = listWorkspaceCommandDefinitions({
+      commands: [
+        { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+        { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+      ],
+    });
+
+    expect(commands).toEqual([
+      expect.objectContaining({ id: "web", kind: "service", serviceIndex: 0 }),
+      expect.objectContaining({ id: "db-migrate", kind: "job", serviceIndex: null }),
+    ]);
+  });
+
+  it("falls back to legacy services and jobs arrays", () => {
+    const commands = listWorkspaceCommandDefinitions({
+      services: [{ name: "web", command: "pnpm dev" }],
+      jobs: [{ name: "lint", command: "pnpm lint" }],
+    });
+
+    expect(commands).toEqual([
+      expect.objectContaining({ id: "service:web", kind: "service", serviceIndex: 0 }),
+      expect.objectContaining({ id: "job:lint", kind: "job", serviceIndex: null }),
+    ]);
+  });
+
+  it("matches a configured service command to the current runtime service", () => {
+    const workspaceRuntime = {
+      commands: [
+        { id: "web", name: "web", kind: "service", command: "pnpm dev", cwd: "." },
+      ],
+    };
+    const command = findWorkspaceCommandDefinition(workspaceRuntime, "web");
+    expect(command).not.toBeNull();
+
+    const match = matchWorkspaceRuntimeServiceToCommand(command!, [
+      {
+        id: "runtime-web",
+        serviceName: "web",
+        command: "pnpm dev",
+        cwd: "/repo",
+        configIndex: null,
+      },
+    ]);
+
+    expect(match).toEqual(expect.objectContaining({ id: "runtime-web" }));
+  });
+});

packages/shared/src/workspace-commands.ts

@@ -0,0 +1,204 @@
+import type { WorkspaceCommandDefinition, WorkspaceRuntimeService } from "./types/workspace-runtime.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readNonEmptyString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function slugify(value: string | null | undefined) {
+  const normalized = (value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+function deriveWorkspaceCommandId(input: {
+  kind: WorkspaceCommandDefinition["kind"];
+  explicitId: string | null;
+  name: string;
+  index: number;
+}) {
+  const explicitId = slugify(input.explicitId);
+  if (explicitId) return explicitId;
+  const nameSlug = slugify(input.name);
+  return nameSlug ? `${input.kind}:${nameSlug}` : `${input.kind}:${input.index + 1}`;
+}
+
+function buildWorkspaceCommandDefinition(input: {
+  entry: Record<string, unknown>;
+  kind: WorkspaceCommandDefinition["kind"];
+  sourceKey: WorkspaceCommandDefinition["source"]["key"];
+  sourceIndex: number;
+  serviceIndex: number | null;
+  fallbackName: string;
+}): WorkspaceCommandDefinition {
+  return {
+    id: deriveWorkspaceCommandId({
+      kind: input.kind,
+      explicitId: readNonEmptyString(input.entry.id),
+      name:
+        readNonEmptyString(input.entry.name)
+        ?? readNonEmptyString(input.entry.label)
+        ?? readNonEmptyString(input.entry.title)
+        ?? input.fallbackName,
+      index: input.sourceIndex,
+    }),
+    name:
+      readNonEmptyString(input.entry.name)
+      ?? readNonEmptyString(input.entry.label)
+      ?? readNonEmptyString(input.entry.title)
+      ?? input.fallbackName,
+    kind: input.kind,
+    command: readNonEmptyString(input.entry.command),
+    cwd: readNonEmptyString(input.entry.cwd),
+    lifecycle:
+      input.kind === "service"
+        ? input.entry.lifecycle === "ephemeral"
+          ? "ephemeral"
+          : "shared"
+        : null,
+    serviceIndex: input.serviceIndex,
+    disabledReason: readNonEmptyString(input.entry.disabledReason),
+    rawConfig: { ...input.entry },
+    source: {
+      type: "paperclip",
+      key: input.sourceKey,
+      index: input.sourceIndex,
+    },
+  };
+}
+
+function uniqueWorkspaceCommandId(
+  seen: Set<string>,
+  commandId: string,
+  sourceKey: WorkspaceCommandDefinition["source"]["key"],
+  sourceIndex: number,
+) {
+  if (!seen.has(commandId)) {
+    seen.add(commandId);
+    return commandId;
+  }
+  const fallbackId = `${commandId}-${sourceKey}-${sourceIndex + 1}`;
+  seen.add(fallbackId);
+  return fallbackId;
+}
+
+function readCommandEntries(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+  key: "commands" | "services" | "jobs",
+) {
+  const raw = workspaceRuntime?.[key];
+  return Array.isArray(raw) ? raw.filter((entry): entry is Record<string, unknown> => isRecord(entry)) : [];
+}
+
+export function listWorkspaceCommandDefinitions(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+): WorkspaceCommandDefinition[] {
+  if (!workspaceRuntime) return [];
+
+  const commandEntries = readCommandEntries(workspaceRuntime, "commands");
+  const seenIds = new Set<string>();
+  let nextServiceIndex = 0;
+
+  const finalize = (command: WorkspaceCommandDefinition) => ({
+    ...command,
+    id: uniqueWorkspaceCommandId(seenIds, command.id, command.source.key, command.source.index),
+  });
+
+  if (commandEntries.length > 0) {
+    return commandEntries.map((entry, index) =>
+      finalize(buildWorkspaceCommandDefinition({
+        entry,
+        kind: entry.kind === "job" ? "job" : "service",
+        sourceKey: "commands",
+        sourceIndex: index,
+        serviceIndex: entry.kind === "job" ? null : nextServiceIndex++,
+        fallbackName: entry.kind === "job" ? `Job ${index + 1}` : `Service ${index + 1}`,
+      })));
+  }
+
+  const serviceDefinitions = readCommandEntries(workspaceRuntime, "services").map((entry, index) =>
+    finalize(buildWorkspaceCommandDefinition({
+      entry,
+      kind: "service",
+      sourceKey: "services",
+      sourceIndex: index,
+      serviceIndex: nextServiceIndex++,
+      fallbackName: `Service ${index + 1}`,
+    })));
+  const jobDefinitions = readCommandEntries(workspaceRuntime, "jobs").map((entry, index) =>
+    finalize(buildWorkspaceCommandDefinition({
+      entry,
+      kind: "job",
+      sourceKey: "jobs",
+      sourceIndex: index,
+      serviceIndex: null,
+      fallbackName: `Job ${index + 1}`,
+    })));
+
+  return [...serviceDefinitions, ...jobDefinitions];
+}
+
+export function listWorkspaceServiceCommandDefinitions(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+) {
+  return listWorkspaceCommandDefinitions(workspaceRuntime).filter((command) => command.kind === "service");
+}
+
+export function findWorkspaceCommandDefinition(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+  workspaceCommandId: string | null | undefined,
+) {
+  const normalizedId = readNonEmptyString(workspaceCommandId);
+  if (!normalizedId) return null;
+  return listWorkspaceCommandDefinitions(workspaceRuntime).find((command) => command.id === normalizedId) ?? null;
+}
+
+export function scoreWorkspaceRuntimeServiceMatch(
+  command: Pick<WorkspaceCommandDefinition, "serviceIndex" | "name" | "command" | "cwd">,
+  runtimeService: Pick<WorkspaceRuntimeService, "configIndex" | "serviceName" | "command" | "cwd">,
+) {
+  if (command.serviceIndex !== null && runtimeService.configIndex !== null && runtimeService.configIndex !== undefined) {
+    return runtimeService.configIndex === command.serviceIndex ? 100 : -1;
+  }
+
+  let score = 0;
+  if (runtimeService.serviceName === command.name) score += 4;
+  if ((runtimeService.command ?? null) === (command.command ?? null)) score += 4;
+  if (
+    command.cwd
+    && runtimeService.cwd
+    && (runtimeService.cwd === command.cwd || runtimeService.cwd.endsWith(`/${command.cwd}`))
+  ) {
+    score += 2;
+  }
+  return score;
+}
+
+export function matchWorkspaceRuntimeServiceToCommand<
+  T extends Pick<WorkspaceRuntimeService, "configIndex" | "serviceName" | "command" | "cwd">,
+>(
+  command: Pick<WorkspaceCommandDefinition, "serviceIndex" | "name" | "command" | "cwd">,
+  runtimeServices: T[] | null | undefined,
+) {
+  let bestMatch: T | null = null;
+  let bestScore = -1;
+
+  for (const runtimeService of runtimeServices ?? []) {
+    const score = scoreWorkspaceRuntimeServiceMatch(command, runtimeService);
+    if (score > bestScore) {
+      bestMatch = runtimeService;
+      bestScore = score;
+    }
+  }
+
+  return bestScore > 0 ? bestMatch : null;
+}

scripts/provision-worktree.sh

@@ -53,6 +53,24 @@ run_paperclipai_command() {
   return 1
 }
 
+paperclipai_command_available() {
+  if command -v pnpm >/dev/null 2>&1 && pnpm paperclipai --help >/dev/null 2>&1; then
+    return 0
+  fi
+
+  local base_cli_tsx_path="$base_cwd/cli/node_modules/tsx/dist/cli.mjs"
+  local base_cli_entry_path="$base_cwd/cli/src/index.ts"
+  if command -v node >/dev/null 2>&1 && [[ -f "$base_cli_tsx_path" ]] && [[ -f "$base_cli_entry_path" ]]; then
+    return 0
+  fi
+
+  if command -v paperclipai >/dev/null 2>&1; then
+    return 0
+  fi
+
+  return 1
+}
+
 run_isolated_worktree_init() {
   run_paperclipai_command \
     worktree \
@@ -318,7 +336,9 @@ main().catch((error) => {
 EOF
 }
 
-if ! run_isolated_worktree_init; then
+if paperclipai_command_available; then
+  run_isolated_worktree_init
+else
   echo "paperclipai CLI not available in this workspace; writing isolated fallback config without DB seeding." >&2
   write_fallback_worktree_config
 fi
@@ -384,14 +404,49 @@ if [[ -f "$worktree_cwd/package.json" && -f "$worktree_cwd/pnpm-lock.yaml" ]]; t
       done
     }
 
-    (
-      cd "$worktree_cwd"
-      pnpm install --frozen-lockfile
-    ) || {
-      restore_moved_symlinks
-      exit 1
+    run_pnpm_install() {
+      local stdout_path stderr_path
+      stdout_path="$(mktemp)"
+      stderr_path="$(mktemp)"
+
+      if (
+        cd "$worktree_cwd"
+        pnpm install "$@"
+      ) >"$stdout_path" 2>"$stderr_path"; then
+        cat "$stdout_path"
+        cat "$stderr_path" >&2
+        rm -f "$stdout_path" "$stderr_path"
+        return 0
+      fi
+
+      local exit_code=$?
+      cat "$stdout_path"
+      cat "$stderr_path" >&2
+      if grep -q "ERR_PNPM_OUTDATED_LOCKFILE" "$stdout_path" "$stderr_path"; then
+        rm -f "$stdout_path" "$stderr_path"
+        return 90
+      fi
+
+      rm -f "$stdout_path" "$stderr_path"
+      return "$exit_code"
     }
 
+    if run_pnpm_install --frozen-lockfile; then
+      :
+    else
+      install_exit_code=$?
+      if [[ "$install_exit_code" -eq 90 ]]; then
+        echo "pnpm-lock.yaml is out of date in this execution workspace; retrying install without --frozen-lockfile." >&2
+        run_pnpm_install --no-frozen-lockfile || {
+          restore_moved_symlinks
+          exit 1
+        }
+      else
+        restore_moved_symlinks
+        exit "$install_exit_code"
+      fi
+    fi
+
     cleanup_moved_symlinks
   fi
 

server/src/__tests__/execution-workspaces-service.test.ts

@@ -43,6 +43,7 @@ describe("execution workspace config helpers", () => {
       teardownCommand: "bash ./scripts/teardown-worktree.sh",
       cleanupCommand: "pkill -f vite || true",
       desiredState: null,
+      serviceStates: null,
       workspaceRuntime: {
         services: [{ name: "web", command: "pnpm dev", port: 3100 }],
       },
@@ -73,6 +74,7 @@ describe("execution workspace config helpers", () => {
         teardownCommand: "bash ./scripts/teardown-worktree.sh",
         cleanupCommand: "pkill -f vite || true",
         desiredState: null,
+        serviceStates: null,
         workspaceRuntime: {
           services: [{ name: "web", command: "pnpm dev" }],
         },

server/src/__tests__/sidebar-preferences-routes.test.ts

@@ -0,0 +1,166 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { sidebarPreferenceRoutes } from "../routes/sidebar-preferences.js";
+
+const mockSidebarPreferenceService = vi.hoisted(() => ({
+  getCompanyOrder: vi.fn(),
+  upsertCompanyOrder: vi.fn(),
+  getProjectOrder: vi.fn(),
+  upsertProjectOrder: vi.fn(),
+}));
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+  sidebarPreferenceService: () => mockSidebarPreferenceService,
+  logActivity: mockLogActivity,
+}));
+
+function createApp(actor: Record<string, unknown>) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = actor as never;
+    next();
+  });
+  app.use("/api", sidebarPreferenceRoutes({} as never));
+  app.use(errorHandler);
+  return app;
+}
+
+const ORDERED_IDS = [
+  "11111111-1111-4111-8111-111111111111",
+  "22222222-2222-4222-8222-222222222222",
+];
+
+describe("sidebar preference routes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSidebarPreferenceService.getCompanyOrder.mockResolvedValue({
+      orderedIds: ORDERED_IDS,
+      updatedAt: null,
+    });
+    mockSidebarPreferenceService.upsertCompanyOrder.mockResolvedValue({
+      orderedIds: ORDERED_IDS,
+      updatedAt: null,
+    });
+    mockSidebarPreferenceService.getProjectOrder.mockResolvedValue({
+      orderedIds: ORDERED_IDS,
+      updatedAt: null,
+    });
+    mockSidebarPreferenceService.upsertProjectOrder.mockResolvedValue({
+      orderedIds: ORDERED_IDS,
+      updatedAt: null,
+    });
+  });
+
+  it("returns company rail order for board users", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-1"],
+    });
+
+    const res = await request(app).get("/api/sidebar-preferences/me");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      orderedIds: ORDERED_IDS,
+      updatedAt: null,
+    });
+    expect(mockSidebarPreferenceService.getCompanyOrder).toHaveBeenCalledWith("user-1");
+  });
+
+  it("updates company rail order for board users", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "local_implicit",
+      isInstanceAdmin: true,
+      companyIds: ["company-1"],
+    });
+
+    const res = await request(app)
+      .put("/api/sidebar-preferences/me")
+      .send({ orderedIds: ORDERED_IDS });
+
+    expect(res.status).toBe(200);
+    expect(mockSidebarPreferenceService.upsertCompanyOrder).toHaveBeenCalledWith("user-1", ORDERED_IDS);
+  });
+
+  it("returns project order for companies the board user can access", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-1"],
+    });
+
+    const res = await request(app).get("/api/companies/company-1/sidebar-preferences/me");
+
+    expect(res.status).toBe(200);
+    expect(mockSidebarPreferenceService.getProjectOrder).toHaveBeenCalledWith("company-1", "user-1");
+  });
+
+  it("logs project order updates for company-scoped writes", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-1"],
+      runId: "run-1",
+    });
+
+    const res = await request(app)
+      .put("/api/companies/company-1/sidebar-preferences/me")
+      .send({ orderedIds: ORDERED_IDS });
+
+    expect(res.status).toBe(200);
+    expect(mockSidebarPreferenceService.upsertProjectOrder).toHaveBeenCalledWith("company-1", "user-1", ORDERED_IDS);
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      {} as never,
+      expect.objectContaining({
+        companyId: "company-1",
+        action: "sidebar_preferences.project_order_updated",
+        details: expect.objectContaining({
+          userId: "user-1",
+          orderedIds: ORDERED_IDS,
+        }),
+      }),
+    );
+  });
+
+  it("rejects company-scoped reads when the board user lacks company access", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "user-1",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: ["company-2"],
+    });
+
+    const res = await request(app).get("/api/companies/company-1/sidebar-preferences/me");
+
+    expect(res.status).toBe(403);
+    expect(mockSidebarPreferenceService.getProjectOrder).not.toHaveBeenCalled();
+  });
+
+  it("rejects agent callers", async () => {
+    const app = createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "company-1",
+      source: "agent_key",
+    });
+
+    const res = await request(app).get("/api/sidebar-preferences/me");
+
+    expect(res.status).toBe(403);
+    expect(mockSidebarPreferenceService.getCompanyOrder).not.toHaveBeenCalled();
+  });
+});

server/src/__tests__/workspace-runtime.test.ts

@@ -19,16 +19,21 @@ import {
 } from "@paperclipai/db";
 import { eq } from "drizzle-orm";
 import {
+  buildWorkspaceRuntimeDesiredStatePatch,
   cleanupExecutionWorkspaceArtifacts,
+  ensurePersistedExecutionWorkspaceAvailable,
   ensureServerWorkspaceLinksCurrent,
   ensureRuntimeServicesForRun,
+  listConfiguredRuntimeServiceEntries,
   normalizeAdapterManagedRuntimeServices,
   reconcilePersistedRuntimeServicesOnStartup,
   realizeExecutionWorkspace,
   releaseRuntimeServicesForRun,
   resetRuntimeServicesForTests,
+  resolveWorkspaceRuntimeReadinessTimeoutSec,
   resolveShell,
   sanitizeRuntimeServiceBaseEnv,
+  startRuntimeServicesForWorkspaceControl,
   stopRuntimeServicesForExecutionWorkspace,
   type RealizedExecutionWorkspace,
 } from "../services/workspace-runtime.ts";
@@ -367,6 +372,42 @@ describe("realizeExecutionWorkspace", () => {
     expect(second.branchName).toBe(first.branchName);
   });
 
+  it("rejects reusing an empty directory that only looks like a worktree because it sits inside the repo", async () => {
+    const repoRoot = await createTempRepo();
+    const branchName = "PAP-447-add-worktree-support";
+    const poisonedPath = path.join(repoRoot, ".paperclip", "worktrees", branchName);
+    await fs.mkdir(poisonedPath, { recursive: true });
+
+    await expect(
+      realizeExecutionWorkspace({
+        base: {
+          baseCwd: repoRoot,
+          source: "project_primary",
+          projectId: "project-1",
+          workspaceId: "workspace-1",
+          repoUrl: null,
+          repoRef: "HEAD",
+        },
+        config: {
+          workspaceStrategy: {
+            type: "git_worktree",
+            branchTemplate: "{{issue.identifier}}-{{slug}}",
+          },
+        },
+        issue: {
+          id: "issue-1",
+          identifier: "PAP-447",
+          title: "Add Worktree Support",
+        },
+        agent: {
+          id: "agent-1",
+          name: "Codex Coder",
+          companyId: "company-1",
+        },
+      }),
+    ).rejects.toThrow(/not a reusable git worktree \(path is not registered in `git worktree list`\)\./);
+  });
+
   it("reuses the current linked worktree instead of nesting another worktree inside it", async () => {
     const repoRoot = await createTempRepo();
     const branchName = "PAP-1355-worktree-reuse";
@@ -408,6 +449,68 @@ describe("realizeExecutionWorkspace", () => {
     await expect(fs.realpath(realized.worktreePath ?? "")).resolves.toBe(expectedWorktreePath);
   });
 
+  it("rejects reusing a linked worktree whose branch drifted from the expected issue branch", async () => {
+    const repoRoot = await createTempRepo();
+
+    const initial = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    await runGit(initial.cwd, ["checkout", "-b", "unexpected-branch"]);
+
+    await expect(
+      realizeExecutionWorkspace({
+        base: {
+          baseCwd: repoRoot,
+          source: "project_primary",
+          projectId: "project-1",
+          workspaceId: "workspace-1",
+          repoUrl: null,
+          repoRef: "HEAD",
+        },
+        config: {
+          workspaceStrategy: {
+            type: "git_worktree",
+            branchTemplate: "{{issue.identifier}}-{{slug}}",
+          },
+        },
+        issue: {
+          id: "issue-1",
+          identifier: "PAP-447",
+          title: "Add Worktree Support",
+        },
+        agent: {
+          id: "agent-1",
+          name: "Codex Coder",
+          companyId: "company-1",
+        },
+      }),
+    ).rejects.toThrow(/not a reusable git worktree \(worktree HEAD is on "unexpected-branch" instead of "PAP-447-add-worktree-support"\)\./);
+  });
+
   it("reuses an already checked out branch from git worktree metadata even when the target path differs", async () => {
     const repoRoot = await createTempRepo();
     const branchName = "PAP-1355-worktree-reuse";
@@ -1033,6 +1136,137 @@ describe("realizeExecutionWorkspace", () => {
     );
   }, 30_000);
 
+  it("fails instead of writing an unseeded fallback config when worktree init errors after CLI detection succeeds", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-provision-fail-"));
+    const baseRoot = path.join(tempRoot, "base");
+    const worktreeRoot = path.join(tempRoot, "worktree");
+    const fakeBin = path.join(tempRoot, "bin");
+    const fakePnpmPath = path.join(fakeBin, "pnpm");
+    const scriptPath = path.join(worktreeRoot, "provision-worktree.sh");
+
+    try {
+      await fs.mkdir(baseRoot, { recursive: true });
+      await fs.mkdir(worktreeRoot, { recursive: true });
+      await fs.mkdir(fakeBin, { recursive: true });
+      await fs.copyFile(provisionWorktreeScriptPath, scriptPath);
+      await fs.chmod(scriptPath, 0o755);
+      await fs.writeFile(
+        fakePnpmPath,
+        [
+          "#!/bin/sh",
+          "if [ \"$1\" = \"paperclipai\" ] && [ \"$2\" = \"--help\" ]; then",
+          "  exit 0",
+          "fi",
+          "if [ \"$1\" = \"paperclipai\" ] && [ \"$2\" = \"worktree\" ] && [ \"$3\" = \"init\" ]; then",
+          "  echo \"simulated init failure\" >&2",
+          "  exit 42",
+          "fi",
+          "exit 0",
+          "",
+        ].join("\n"),
+        "utf8",
+      );
+      await fs.chmod(fakePnpmPath, 0o755);
+
+      let caught: Error | null = null;
+      try {
+        await execFileAsync(scriptPath, [], {
+          cwd: worktreeRoot,
+          env: {
+            ...process.env,
+            PATH: `${fakeBin}:${process.env.PATH ?? ""}`,
+            PAPERCLIP_WORKSPACE_BASE_CWD: baseRoot,
+            PAPERCLIP_WORKSPACE_CWD: worktreeRoot,
+          },
+        });
+      } catch (error) {
+        caught = error as Error;
+      }
+
+      expect(caught).toBeTruthy();
+      expect(String(caught)).toContain("simulated init failure");
+      await expect(fs.stat(path.join(worktreeRoot, ".paperclip", "config.json"))).rejects.toThrow();
+      await expect(fs.stat(path.join(worktreeRoot, ".paperclip", ".env"))).rejects.toThrow();
+    } finally {
+      await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("retries worktree-local pnpm install without a frozen lockfile when the lockfile is outdated", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-outdated-lockfile-"));
+    const baseRoot = path.join(tempRoot, "base");
+    const worktreeRoot = path.join(tempRoot, "worktree");
+    const fakeBin = path.join(tempRoot, "bin");
+    const fakePnpmPath = path.join(fakeBin, "pnpm");
+    const scriptPath = path.join(worktreeRoot, "provision-worktree.sh");
+
+    try {
+      await fs.mkdir(path.join(baseRoot, "node_modules"), { recursive: true });
+      await fs.mkdir(worktreeRoot, { recursive: true });
+      await fs.mkdir(fakeBin, { recursive: true });
+      await fs.copyFile(provisionWorktreeScriptPath, scriptPath);
+      await fs.chmod(scriptPath, 0o755);
+      await fs.writeFile(
+        path.join(worktreeRoot, "package.json"),
+        JSON.stringify(
+          {
+            name: "workspace-root",
+            private: true,
+            packageManager: "pnpm@9.15.4",
+          },
+          null,
+          2,
+        ),
+        "utf8",
+      );
+      await fs.writeFile(
+        path.join(worktreeRoot, "pnpm-lock.yaml"),
+        ["lockfileVersion: '9.0'", "", "importers:", "  .: {}", ""].join("\n"),
+        "utf8",
+      );
+      await fs.writeFile(
+        fakePnpmPath,
+        [
+          "#!/bin/sh",
+          "if [ \"$1\" = \"paperclipai\" ] && [ \"$2\" = \"--help\" ]; then",
+          "  exit 1",
+          "fi",
+          "if [ \"$1\" = \"install\" ] && [ \"$2\" = \"--frozen-lockfile\" ]; then",
+          "  echo \"ERR_PNPM_OUTDATED_LOCKFILE\" >&2",
+          "  exit 1",
+          "fi",
+          "if [ \"$1\" = \"install\" ] && [ \"$2\" = \"--no-frozen-lockfile\" ]; then",
+          "  mkdir -p \"$PWD/node_modules\"",
+          "  : > \"$PWD/node_modules/.retry-success\"",
+          "  exit 0",
+          "fi",
+          "exit 0",
+          "",
+        ].join("\n"),
+        "utf8",
+      );
+      await fs.chmod(fakePnpmPath, 0o755);
+
+      const result = await execFileAsync(scriptPath, [], {
+        cwd: worktreeRoot,
+        env: {
+          ...process.env,
+          PATH: `${fakeBin}:${process.env.PATH ?? ""}`,
+          PAPERCLIP_WORKSPACE_BASE_CWD: baseRoot,
+          PAPERCLIP_WORKSPACE_CWD: worktreeRoot,
+        },
+      });
+
+      expect(result.stderr).toContain("retrying install without --frozen-lockfile");
+      await expect(fs.readFile(path.join(worktreeRoot, "node_modules", ".retry-success"), "utf8")).resolves.toBe("");
+      await expect(fs.readFile(path.join(worktreeRoot, ".paperclip", "config.json"), "utf8")).resolves.toContain(
+        "\"database\"",
+      );
+    } finally {
+      await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+
   it(
     "provisions worktree-local pnpm node_modules instead of reusing base-repo links",
     async () => {
@@ -1290,6 +1524,187 @@ describe("realizeExecutionWorkspace", () => {
     expect(actualHead).toBe(expectedHead);
   });
 
+  it("reattaches a missing persisted git worktree before manual control starts it", async () => {
+    const repoRoot = await createTempRepo();
+    const branchName = "PAP-451-restore-persisted-worktree";
+    await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, "scripts", "restore.sh"),
+      [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        "printf '%s\\n' \"$PAPERCLIP_WORKSPACE_BRANCH\" > .paperclip-restored-branch",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.chmod(path.join(repoRoot, "scripts", "restore.sh"), 0o755);
+    await runGit(repoRoot, ["add", "scripts/restore.sh"]);
+    await runGit(repoRoot, ["commit", "-m", "Add restore script"]);
+
+    await runGit(repoRoot, ["checkout", "-b", branchName]);
+    await fs.writeFile(path.join(repoRoot, "feature.txt"), "persisted\n", "utf8");
+    await runGit(repoRoot, ["add", "feature.txt"]);
+    await runGit(repoRoot, ["commit", "-m", "Add persisted feature"]);
+    const expectedHead = (await execFileAsync("git", ["rev-parse", branchName], { cwd: repoRoot })).stdout.trim();
+    await runGit(repoRoot, ["checkout", "main"]);
+
+    const initial = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+          provisionCommand: "bash ./scripts/restore.sh",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-451",
+        title: "Restore persisted worktree",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    await fs.rm(initial.cwd, { recursive: true, force: true });
+
+    const restored = await ensurePersistedExecutionWorkspaceAvailable({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      workspace: {
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        cwd: initial.cwd,
+        providerRef: initial.worktreePath,
+        projectId: "project-1",
+        projectWorkspaceId: "workspace-1",
+        repoUrl: null,
+        baseRef: "HEAD",
+        branchName,
+        config: {
+          provisionCommand: "bash ./scripts/restore.sh",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-451",
+        title: "Restore persisted worktree",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(restored).not.toBeNull();
+    expect(restored?.cwd).toBe(initial.cwd);
+    await expect(fs.readFile(path.join(initial.cwd, "feature.txt"), "utf8")).resolves.toBe("persisted\n");
+    await expect(fs.readFile(path.join(initial.cwd, ".paperclip-restored-branch"), "utf8")).resolves.toBe(`${branchName}\n`);
+    const actualHead = (await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: initial.cwd })).stdout.trim();
+    expect(actualHead).toBe(expectedHead);
+  });
+
+  it("reprovisions an existing persisted git worktree before manual control starts it", async () => {
+    const repoRoot = await createTempRepo();
+    await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, "scripts", "restore.sh"),
+      [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        "printf 'reprovisioned\\n' > .paperclip-restored-state",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.chmod(path.join(repoRoot, "scripts", "restore.sh"), 0o755);
+    await runGit(repoRoot, ["add", "scripts/restore.sh"]);
+    await runGit(repoRoot, ["commit", "-m", "Add reprovision script"]);
+
+    const initial = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+          provisionCommand: "bash ./scripts/restore.sh",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-452",
+        title: "Reprovision persisted worktree",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    await fs.rm(path.join(initial.cwd, ".paperclip-restored-state"), { force: true });
+
+    await ensurePersistedExecutionWorkspaceAvailable({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      workspace: {
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        cwd: initial.cwd,
+        providerRef: initial.worktreePath,
+        projectId: "project-1",
+        projectWorkspaceId: "workspace-1",
+        repoUrl: null,
+        baseRef: "HEAD",
+        branchName: initial.branchName,
+        config: {
+          provisionCommand: "bash ./scripts/restore.sh",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-452",
+        title: "Reprovision persisted worktree",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    await expect(fs.readFile(path.join(initial.cwd, ".paperclip-restored-state"), "utf8")).resolves.toBe("reprovisioned\n");
+  });
+
   it("auto-detects the default branch when baseRef is not configured", async () => {
     // Create a repo with "master" as default branch (not "main")
     const repoRoot = await createTempRepo("master");
@@ -1977,6 +2392,234 @@ describe("ensureRuntimeServicesForRun", () => {
     await releaseRuntimeServicesForRun(runId);
     leasedRunIds.delete(runId);
   });
+
+  it("starts only the selected workspace-controlled runtime service", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-control-start-"));
+    const workspace = buildWorkspace(workspaceRoot);
+
+    const services = await startRuntimeServicesForWorkspaceControl({
+      actor: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace,
+      executionWorkspaceId: "execution-workspace-control-start",
+      config: {
+        workspaceRuntime: {
+          services: [
+            {
+              name: "web",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('web')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "execution_workspace",
+            },
+            {
+              name: "worker",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('worker')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "execution_workspace",
+            },
+          ],
+        },
+      },
+      adapterEnv: {},
+      serviceIndex: 1,
+    });
+
+    expect(services).toHaveLength(1);
+    expect(services[0]?.serviceName).toBe("worker");
+    await expect(fetch(services[0]!.url!)).resolves.toMatchObject({ ok: true });
+
+    await stopRuntimeServicesForExecutionWorkspace({
+      executionWorkspaceId: "execution-workspace-control-start",
+      workspaceCwd: workspace.cwd,
+    });
+  });
+
+  it("stops only the selected execution workspace runtime service", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-control-stop-"));
+    const workspace = buildWorkspace(workspaceRoot);
+
+    const services = await startRuntimeServicesForWorkspaceControl({
+      actor: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace,
+      executionWorkspaceId: "execution-workspace-control-stop",
+      config: {
+        workspaceRuntime: {
+          services: [
+            {
+              name: "web",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('web')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "execution_workspace",
+              stopPolicy: {
+                type: "manual",
+              },
+            },
+            {
+              name: "worker",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('worker')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "execution_workspace",
+              stopPolicy: {
+                type: "manual",
+              },
+            },
+          ],
+        },
+      },
+      adapterEnv: {},
+    });
+
+    expect(services).toHaveLength(2);
+    const web = services.find((service) => service.serviceName === "web");
+    const worker = services.find((service) => service.serviceName === "worker");
+
+    await stopRuntimeServicesForExecutionWorkspace({
+      executionWorkspaceId: "execution-workspace-control-stop",
+      workspaceCwd: workspace.cwd,
+      runtimeServiceId: web?.id ?? null,
+    });
+
+    await expect(fetch(web!.url!)).rejects.toThrow();
+    await expect(fetch(worker!.url!)).resolves.toMatchObject({ ok: true });
+
+    await stopRuntimeServicesForExecutionWorkspace({
+      executionWorkspaceId: "execution-workspace-control-stop",
+      workspaceCwd: workspace.cwd,
+      runtimeServiceId: worker?.id ?? null,
+    });
+  });
+});
+
+describe("buildWorkspaceRuntimeDesiredStatePatch", () => {
+  it("derives service entries from command-first runtime config", () => {
+    const services = listConfiguredRuntimeServiceEntries({
+      workspaceRuntime: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+          { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+        ],
+      },
+    });
+
+    expect(services).toEqual([
+      expect.objectContaining({
+        id: "web",
+        kind: "service",
+        command: "pnpm dev",
+      }),
+    ]);
+  });
+
+  it("preserves sibling service state when updating a single configured runtime service", () => {
+    const patch = buildWorkspaceRuntimeDesiredStatePatch({
+      config: {
+        workspaceRuntime: {
+          services: [
+            { name: "web", command: "pnpm dev" },
+            { name: "worker", command: "pnpm worker" },
+          ],
+        },
+      },
+      currentDesiredState: "running",
+      currentServiceStates: null,
+      action: "stop",
+      serviceIndex: 1,
+    });
+
+    expect(patch).toEqual({
+      desiredState: "running",
+      serviceStates: {
+        "0": "running",
+        "1": "stopped",
+      },
+    });
+  });
+});
+
+describe("resolveWorkspaceRuntimeReadinessTimeoutSec", () => {
+  it("extends the default readiness timeout for dev-server commands", () => {
+    expect(
+      resolveWorkspaceRuntimeReadinessTimeoutSec({
+        command: "pnpm dev",
+        readiness: {
+          type: "http",
+          urlTemplate: "http://127.0.0.1:{{port}}",
+        },
+      }),
+    ).toBe(90);
+    expect(
+      resolveWorkspaceRuntimeReadinessTimeoutSec({
+        command: "npm run dev -- --host 127.0.0.1",
+        readiness: {
+          type: "http",
+          urlTemplate: "http://127.0.0.1:{{port}}",
+        },
+      }),
+    ).toBe(90);
+  });
+
+  it("keeps explicit readiness timeouts and non-dev defaults unchanged", () => {
+    expect(
+      resolveWorkspaceRuntimeReadinessTimeoutSec({
+        command: "pnpm dev",
+        readiness: {
+          type: "http",
+          timeoutSec: 12,
+          urlTemplate: "http://127.0.0.1:{{port}}",
+        },
+      }),
+    ).toBe(12);
+    expect(
+      resolveWorkspaceRuntimeReadinessTimeoutSec({
+        command: "node server.js",
+        readiness: {
+          type: "http",
+          urlTemplate: "http://127.0.0.1:{{port}}",
+        },
+      }),
+    ).toBe(30);
+  });
 });
 
 describe("resolveShell (shell fallback)", () => {
@@ -1993,13 +2636,18 @@ describe("resolveShell (shell fallback)", () => {
   });
 
   it("returns process.env.SHELL when set", () => {
-    process.env.SHELL = "/usr/bin/zsh";
-    expect(resolveShell()).toBe("/usr/bin/zsh");
+    process.env.SHELL = process.execPath;
+    expect(resolveShell()).toBe(process.execPath);
   });
 
   it("trims whitespace from SHELL env var", () => {
-    process.env.SHELL = "  /usr/bin/fish  ";
-    expect(resolveShell()).toBe("/usr/bin/fish");
+    process.env.SHELL = `  ${process.execPath}  `;
+    expect(resolveShell()).toBe(process.execPath);
+  });
+
+  it("preserves non-absolute shell names so PATH lookup still works", () => {
+    process.env.SHELL = "zsh";
+    expect(resolveShell()).toBe("zsh");
   });
 
   it("falls back to /bin/sh on non-Windows when SHELL is unset", () => {
@@ -2031,6 +2679,12 @@ describe("resolveShell (shell fallback)", () => {
     Object.defineProperty(process, "platform", { value: "win32" });
     expect(resolveShell()).toBe("sh");
   });
+
+  it("falls back when SHELL points to a missing absolute path", () => {
+    process.env.SHELL = "/definitely/missing/zsh";
+    Object.defineProperty(process, "platform", { value: "linux" });
+    expect(resolveShell()).toBe("/bin/sh");
+  });
 });
 
 describeEmbeddedPostgres("workspace runtime startup reconciliation", () => {

server/src/app.ts

@@ -24,6 +24,7 @@ import { costRoutes } from "./routes/costs.js";
 import { activityRoutes } from "./routes/activity.js";
 import { dashboardRoutes } from "./routes/dashboard.js";
 import { sidebarBadgeRoutes } from "./routes/sidebar-badges.js";
+import { sidebarPreferenceRoutes } from "./routes/sidebar-preferences.js";
 import { inboxDismissalRoutes } from "./routes/inbox-dismissals.js";
 import { instanceSettingsRoutes } from "./routes/instance-settings.js";
 import { llmRoutes } from "./routes/llms.js";
@@ -167,6 +168,7 @@ export async function createApp(
   api.use(activityRoutes(db));
   api.use(dashboardRoutes(db));
   api.use(sidebarBadgeRoutes(db));
+  api.use(sidebarPreferenceRoutes(db));
   api.use(inboxDismissalRoutes(db));
   api.use(instanceSettingsRoutes(db));
   const hostServicesDisposers = new Map<string, () => void>();

server/src/routes/execution-workspaces.ts

@@ -1,15 +1,24 @@
 import { and, eq } from "drizzle-orm";
-import { Router } from "express";
+import { Router, type Request, type Response } from "express";
 import type { Db } from "@paperclipai/db";
 import { issues, projects, projectWorkspaces } from "@paperclipai/db";
-import { updateExecutionWorkspaceSchema } from "@paperclipai/shared";
+import {
+  findWorkspaceCommandDefinition,
+  matchWorkspaceRuntimeServiceToCommand,
+  updateExecutionWorkspaceSchema,
+  workspaceRuntimeControlTargetSchema,
+} from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
 import { executionWorkspaceService, logActivity, workspaceOperationService } from "../services/index.js";
 import { mergeExecutionWorkspaceConfig, readExecutionWorkspaceConfig } from "../services/execution-workspaces.js";
 import { parseProjectExecutionWorkspacePolicy } from "../services/execution-workspace-policy.js";
 import { readProjectWorkspaceRuntimeConfig } from "../services/project-workspace-runtime-config.js";
 import {
+  buildWorkspaceRuntimeDesiredStatePatch,
   cleanupExecutionWorkspaceArtifacts,
+  ensurePersistedExecutionWorkspaceAvailable,
+  listConfiguredRuntimeServiceEntries,
+  runWorkspaceJobForControl,
   startRuntimeServicesForWorkspaceControl,
   stopRuntimeServicesForExecutionWorkspace,
 } from "../services/workspace-runtime.js";
@@ -72,11 +81,11 @@ export function executionWorkspaceRoutes(db: Db) {
     res.json(operations);
   });
 
-  router.post("/execution-workspaces/:id/runtime-services/:action", async (req, res) => {
+  async function handleExecutionWorkspaceRuntimeCommand(req: Request, res: Response) {
     const id = req.params.id as string;
     const action = String(req.params.action ?? "").trim().toLowerCase();
-    if (action !== "start" && action !== "stop" && action !== "restart") {
-      res.status(404).json({ error: "Runtime service action not found" });
+    if (action !== "start" && action !== "stop" && action !== "restart" && action !== "run") {
+      res.status(404).json({ error: "Workspace command action not found" });
       return;
     }
 
@@ -89,7 +98,7 @@ export function executionWorkspaceRoutes(db: Db) {
 
     const workspaceCwd = existing.cwd;
     if (!workspaceCwd) {
-      res.status(422).json({ error: "Execution workspace needs a local path before Paperclip can manage local runtime services" });
+      res.status(422).json({ error: "Execution workspace needs a local path before Paperclip can run workspace commands" });
       return;
     }
 
@@ -115,10 +124,68 @@ export function executionWorkspaceRoutes(db: Db) {
     const projectWorkspaceRuntime = readProjectWorkspaceRuntimeConfig(
       (projectWorkspace?.metadata as Record<string, unknown> | null) ?? null,
     )?.workspaceRuntime ?? null;
+    const projectPolicy = existing.projectId
+      ? await db
+          .select({
+            executionWorkspacePolicy: projects.executionWorkspacePolicy,
+          })
+          .from(projects)
+          .where(
+            and(
+              eq(projects.id, existing.projectId),
+              eq(projects.companyId, existing.companyId),
+            ),
+          )
+          .then((rows) => parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy))
+      : null;
     const effectiveRuntimeConfig = existing.config?.workspaceRuntime ?? projectWorkspaceRuntime ?? null;
+    const target = req.body as { workspaceCommandId?: string | null; runtimeServiceId?: string | null; serviceIndex?: number | null };
+    const configuredServices = effectiveRuntimeConfig
+      ? listConfiguredRuntimeServiceEntries({ workspaceRuntime: effectiveRuntimeConfig })
+      : [];
+    const workspaceCommand = effectiveRuntimeConfig
+      ? findWorkspaceCommandDefinition(effectiveRuntimeConfig, target.workspaceCommandId ?? null)
+      : null;
+    if (target.workspaceCommandId && !workspaceCommand) {
+      res.status(404).json({ error: "Workspace command not found for this execution workspace" });
+      return;
+    }
+    if (target.runtimeServiceId && !(existing.runtimeServices ?? []).some((service) => service.id === target.runtimeServiceId)) {
+      res.status(404).json({ error: "Runtime service not found for this execution workspace" });
+      return;
+    }
+    const matchedRuntimeService =
+      workspaceCommand?.kind === "service" && !target.runtimeServiceId
+        ? matchWorkspaceRuntimeServiceToCommand(workspaceCommand, existing.runtimeServices ?? [])
+        : null;
+    const selectedRuntimeServiceId = target.runtimeServiceId ?? matchedRuntimeService?.id ?? null;
+    const selectedServiceIndex =
+      workspaceCommand?.kind === "service"
+        ? workspaceCommand.serviceIndex
+        : target.serviceIndex ?? null;
+    if (
+      selectedServiceIndex !== undefined
+      && selectedServiceIndex !== null
+      && (selectedServiceIndex < 0 || selectedServiceIndex >= configuredServices.length)
+    ) {
+      res.status(422).json({ error: "Selected runtime service is not defined in this execution workspace runtime config" });
+      return;
+    }
+    if (workspaceCommand?.kind === "job" && action !== "run") {
+      res.status(422).json({ error: `Workspace job "${workspaceCommand.name}" can only be run` });
+      return;
+    }
+    if (workspaceCommand?.kind === "service" && action === "run") {
+      res.status(422).json({ error: `Workspace service "${workspaceCommand.name}" should be started or restarted, not run` });
+      return;
+    }
+    if (action === "run" && !workspaceCommand) {
+      res.status(422).json({ error: "Select a workspace job to run" });
+      return;
+    }
 
     if ((action === "start" || action === "restart") && !effectiveRuntimeConfig) {
-      res.status(422).json({ error: "Execution workspace has no runtime service configuration or inherited project workspace default" });
+      res.status(422).json({ error: "Execution workspace has no workspace command configuration or inherited project workspace default" });
       return;
     }
 
@@ -133,13 +200,101 @@ export function executionWorkspaceRoutes(db: Db) {
 
     const operation = await recorder.recordOperation({
       phase: action === "stop" ? "workspace_teardown" : "workspace_provision",
-      command: `workspace runtime ${action}`,
+      command: workspaceCommand?.command ?? `workspace command ${action}`,
       cwd: existing.cwd,
       metadata: {
         action,
         executionWorkspaceId: existing.id,
+        workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+        workspaceCommandKind: workspaceCommand?.kind ?? null,
+        workspaceCommandName: workspaceCommand?.name ?? null,
+        runtimeServiceId: selectedRuntimeServiceId,
+        serviceIndex: selectedServiceIndex,
       },
       run: async () => {
+        const ensureWorkspaceAvailable = async () =>
+          await ensurePersistedExecutionWorkspaceAvailable({
+            base: {
+              baseCwd: projectWorkspace?.cwd ?? workspaceCwd,
+              source: existing.mode === "shared_workspace" ? "project_primary" : "task_session",
+              projectId: existing.projectId,
+              workspaceId: existing.projectWorkspaceId,
+              repoUrl: existing.repoUrl,
+              repoRef: existing.baseRef,
+            },
+            workspace: {
+              mode: existing.mode,
+              strategyType: existing.strategyType,
+              cwd: existing.cwd,
+              providerRef: existing.providerRef,
+              projectId: existing.projectId,
+              projectWorkspaceId: existing.projectWorkspaceId,
+              repoUrl: existing.repoUrl,
+              baseRef: existing.baseRef,
+              branchName: existing.branchName,
+              config: {
+                ...existing.config,
+                provisionCommand:
+                  existing.config?.provisionCommand
+                  ?? projectPolicy?.workspaceStrategy?.provisionCommand
+                  ?? null,
+              },
+            },
+            issue: existing.sourceIssueId
+              ? {
+                  id: existing.sourceIssueId,
+                  identifier: null,
+                  title: existing.name,
+                }
+              : null,
+            agent: {
+              id: actor.agentId ?? null,
+              name: actor.actorType === "user" ? "Board" : "Agent",
+              companyId: existing.companyId,
+            },
+            recorder,
+          });
+
+        if (action === "run") {
+          if (!workspaceCommand || workspaceCommand.kind !== "job") {
+            throw new Error("Workspace job selection is required");
+          }
+          const availableWorkspace = await ensureWorkspaceAvailable();
+          if (!availableWorkspace) {
+            throw new Error("Execution workspace needs a local path before Paperclip can run workspace commands");
+          }
+          return await runWorkspaceJobForControl({
+            actor: {
+              id: actor.agentId ?? null,
+              name: actor.actorType === "user" ? "Board" : "Agent",
+              companyId: existing.companyId,
+            },
+            issue: existing.sourceIssueId
+              ? {
+                  id: existing.sourceIssueId,
+                  identifier: null,
+                  title: existing.name,
+                }
+              : null,
+            workspace: availableWorkspace,
+            command: workspaceCommand.rawConfig,
+            adapterEnv: {},
+            recorder,
+            metadata: {
+              action,
+              executionWorkspaceId: existing.id,
+              workspaceCommandId: workspaceCommand.id,
+            },
+          }).then((nestedOperation) => ({
+            status: "succeeded" as const,
+            exitCode: 0,
+            metadata: {
+              nestedOperationId: nestedOperation?.id ?? null,
+              runtimeServiceCount,
+            },
+          }));
+        }
+
         const onLog = async (stream: "stdout" | "stderr", chunk: string) => {
           if (stream === "stdout") stdout.push(chunk);
           else stderr.push(chunk);
@@ -150,10 +305,15 @@ export function executionWorkspaceRoutes(db: Db) {
             db,
             executionWorkspaceId: existing.id,
             workspaceCwd,
+            runtimeServiceId: selectedRuntimeServiceId,
           });
         }
 
         if (action === "start" || action === "restart") {
+          const availableWorkspace = await ensureWorkspaceAvailable();
+          if (!availableWorkspace) {
+            throw new Error("Execution workspace needs a local path before Paperclip can manage local runtime services");
+          }
           const startedServices = await startRuntimeServicesForWorkspaceControl({
             db,
             actor: {
@@ -168,32 +328,41 @@ export function executionWorkspaceRoutes(db: Db) {
                   title: existing.name,
                 }
               : null,
-            workspace: {
-              baseCwd: workspaceCwd,
-              source: existing.mode === "shared_workspace" ? "project_primary" : "task_session",
-              projectId: existing.projectId,
-              workspaceId: existing.projectWorkspaceId,
-              repoUrl: existing.repoUrl,
-              repoRef: existing.baseRef,
-              strategy: existing.strategyType === "git_worktree" ? "git_worktree" : "project_primary",
-              cwd: workspaceCwd,
-              branchName: existing.branchName,
-              worktreePath: existing.strategyType === "git_worktree" ? workspaceCwd : null,
-              warnings: [],
-              created: false,
-            },
+            workspace: availableWorkspace,
             executionWorkspaceId: existing.id,
             config: { workspaceRuntime: effectiveRuntimeConfig },
             adapterEnv: {},
             onLog,
+            serviceIndex: selectedServiceIndex,
           });
           runtimeServiceCount = startedServices.length;
         } else {
-          runtimeServiceCount = 0;
+          runtimeServiceCount = selectedRuntimeServiceId ? Math.max(0, (existing.runtimeServices?.length ?? 1) - 1) : 0;
         }
 
+        const currentDesiredState: "running" | "stopped" =
+          existing.config?.desiredState
+          ?? ((existing.runtimeServices ?? []).some((service) => service.status === "starting" || service.status === "running")
+            ? "running"
+            : "stopped");
+        const nextRuntimeState: {
+          desiredState: "running" | "stopped";
+          serviceStates: Record<string, "running" | "stopped"> | null | undefined;
+        } = selectedRuntimeServiceId && (selectedServiceIndex === undefined || selectedServiceIndex === null)
+          ? {
+              desiredState: currentDesiredState,
+              serviceStates: existing.config?.serviceStates ?? null,
+            }
+          : buildWorkspaceRuntimeDesiredStatePatch({
+              config: { workspaceRuntime: effectiveRuntimeConfig },
+              currentDesiredState,
+              currentServiceStates: existing.config?.serviceStates ?? null,
+              action,
+              serviceIndex: selectedServiceIndex,
+            });
         const metadata = mergeExecutionWorkspaceConfig(existing.metadata as Record<string, unknown> | null, {
-          desiredState: action === "stop" ? "stopped" : "running",
+          desiredState: nextRuntimeState.desiredState,
+          serviceStates: nextRuntimeState.serviceStates,
         });
         await svc.update(existing.id, { metadata });
 
@@ -209,6 +378,9 @@ export function executionWorkspaceRoutes(db: Db) {
                 : "Started execution workspace runtime services.\n",
           metadata: {
             runtimeServiceCount,
+            workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+            runtimeServiceId: selectedRuntimeServiceId,
+            serviceIndex: selectedServiceIndex,
           },
         };
       },
@@ -231,6 +403,11 @@ export function executionWorkspaceRoutes(db: Db) {
       entityId: existing.id,
       details: {
         runtimeServiceCount,
+        workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+        workspaceCommandKind: workspaceCommand?.kind ?? null,
+        workspaceCommandName: workspaceCommand?.name ?? null,
+        runtimeServiceId: selectedRuntimeServiceId,
+        serviceIndex: selectedServiceIndex,
       },
     });
 
@@ -238,7 +415,10 @@ export function executionWorkspaceRoutes(db: Db) {
       workspace,
       operation,
     });
-  });
+  }
+
+  router.post("/execution-workspaces/:id/runtime-services/:action", validate(workspaceRuntimeControlTargetSchema), handleExecutionWorkspaceRuntimeCommand);
+  router.post("/execution-workspaces/:id/runtime-commands/:action", validate(workspaceRuntimeControlTargetSchema), handleExecutionWorkspaceRuntimeCommand);
 
   router.patch("/execution-workspaces/:id", validate(updateExecutionWorkspaceSchema), async (req, res) => {
     const id = req.params.id as string;

server/src/routes/index.ts

@@ -12,6 +12,7 @@ export { costRoutes } from "./costs.js";
 export { activityRoutes } from "./activity.js";
 export { dashboardRoutes } from "./dashboard.js";
 export { sidebarBadgeRoutes } from "./sidebar-badges.js";
+export { sidebarPreferenceRoutes } from "./sidebar-preferences.js";
 export { inboxDismissalRoutes } from "./inbox-dismissals.js";
 export { llmRoutes } from "./llms.js";
 export { accessRoutes } from "./access.js";

server/src/routes/projects.ts

@@ -1,18 +1,27 @@
-import { Router, type Request } from "express";
+import { Router, type Request, type Response } from "express";
 import type { Db } from "@paperclipai/db";
 import {
   createProjectSchema,
   createProjectWorkspaceSchema,
+  findWorkspaceCommandDefinition,
   isUuidLike,
+  matchWorkspaceRuntimeServiceToCommand,
   updateProjectSchema,
   updateProjectWorkspaceSchema,
+  workspaceRuntimeControlTargetSchema,
 } from "@paperclipai/shared";
 import { trackProjectCreated } from "@paperclipai/shared/telemetry";
 import { validate } from "../middleware/validate.js";
 import { projectService, logActivity, secretService, workspaceOperationService } from "../services/index.js";
 import { conflict } from "../errors.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
-import { startRuntimeServicesForWorkspaceControl, stopRuntimeServicesForProjectWorkspace } from "../services/workspace-runtime.js";
+import {
+  buildWorkspaceRuntimeDesiredStatePatch,
+  listConfiguredRuntimeServiceEntries,
+  runWorkspaceJobForControl,
+  startRuntimeServicesForWorkspaceControl,
+  stopRuntimeServicesForProjectWorkspace,
+} from "../services/workspace-runtime.js";
 import { getTelemetryClient } from "../telemetry.js";
 
 export function projectRoutes(db: Db) {
@@ -259,12 +268,12 @@ export function projectRoutes(db: Db) {
     },
   );
 
-  router.post("/projects/:id/workspaces/:workspaceId/runtime-services/:action", async (req, res) => {
+  async function handleProjectWorkspaceRuntimeCommand(req: Request, res: Response) {
     const id = req.params.id as string;
     const workspaceId = req.params.workspaceId as string;
     const action = String(req.params.action ?? "").trim().toLowerCase();
-    if (action !== "start" && action !== "stop" && action !== "restart") {
-      res.status(404).json({ error: "Runtime service action not found" });
+    if (action !== "start" && action !== "stop" && action !== "restart" && action !== "run") {
+      res.status(404).json({ error: "Workspace command action not found" });
       return;
     }
 
@@ -283,13 +292,55 @@ export function projectRoutes(db: Db) {
 
     const workspaceCwd = workspace.cwd;
     if (!workspaceCwd) {
-      res.status(422).json({ error: "Project workspace needs a local path before Paperclip can manage local runtime services" });
+      res.status(422).json({ error: "Project workspace needs a local path before Paperclip can run workspace commands" });
       return;
     }
 
     const runtimeConfig = workspace.runtimeConfig?.workspaceRuntime ?? null;
+    const target = req.body as { workspaceCommandId?: string | null; runtimeServiceId?: string | null; serviceIndex?: number | null };
+    const configuredServices = runtimeConfig ? listConfiguredRuntimeServiceEntries({ workspaceRuntime: runtimeConfig }) : [];
+    const workspaceCommand = runtimeConfig
+      ? findWorkspaceCommandDefinition(runtimeConfig, target.workspaceCommandId ?? null)
+      : null;
+    if (target.workspaceCommandId && !workspaceCommand) {
+      res.status(404).json({ error: "Workspace command not found for this project workspace" });
+      return;
+    }
+    if (target.runtimeServiceId && !(workspace.runtimeServices ?? []).some((service) => service.id === target.runtimeServiceId)) {
+      res.status(404).json({ error: "Runtime service not found for this project workspace" });
+      return;
+    }
+    const matchedRuntimeService =
+      workspaceCommand?.kind === "service" && !target.runtimeServiceId
+        ? matchWorkspaceRuntimeServiceToCommand(workspaceCommand, workspace.runtimeServices ?? [])
+        : null;
+    const selectedRuntimeServiceId = target.runtimeServiceId ?? matchedRuntimeService?.id ?? null;
+    const selectedServiceIndex =
+      workspaceCommand?.kind === "service"
+        ? workspaceCommand.serviceIndex
+        : target.serviceIndex ?? null;
+    if (
+      selectedServiceIndex !== undefined
+      && selectedServiceIndex !== null
+      && (selectedServiceIndex < 0 || selectedServiceIndex >= configuredServices.length)
+    ) {
+      res.status(422).json({ error: "Selected runtime service is not defined in this project workspace runtime config" });
+      return;
+    }
+    if (workspaceCommand?.kind === "job" && action !== "run") {
+      res.status(422).json({ error: `Workspace job "${workspaceCommand.name}" can only be run` });
+      return;
+    }
+    if (workspaceCommand?.kind === "service" && action === "run") {
+      res.status(422).json({ error: `Workspace service "${workspaceCommand.name}" should be started or restarted, not run` });
+      return;
+    }
+    if (action === "run" && !workspaceCommand) {
+      res.status(422).json({ error: "Select a workspace job to run" });
+      return;
+    }
     if ((action === "start" || action === "restart") && !runtimeConfig) {
-      res.status(422).json({ error: "Project workspace has no runtime service configuration" });
+      res.status(422).json({ error: "Project workspace has no workspace command configuration" });
       return;
     }
 
@@ -301,14 +352,63 @@ export function projectRoutes(db: Db) {
 
     const operation = await recorder.recordOperation({
       phase: action === "stop" ? "workspace_teardown" : "workspace_provision",
-      command: `workspace runtime ${action}`,
+      command: workspaceCommand?.command ?? `workspace command ${action}`,
       cwd: workspace.cwd,
       metadata: {
         action,
         projectId: project.id,
         projectWorkspaceId: workspace.id,
+        workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+        workspaceCommandKind: workspaceCommand?.kind ?? null,
+        workspaceCommandName: workspaceCommand?.name ?? null,
+        runtimeServiceId: selectedRuntimeServiceId,
+        serviceIndex: selectedServiceIndex,
       },
       run: async () => {
+        if (action === "run") {
+          if (!workspaceCommand || workspaceCommand.kind !== "job") {
+            throw new Error("Workspace job selection is required");
+          }
+          return await runWorkspaceJobForControl({
+            actor: {
+              id: actor.agentId ?? null,
+              name: actor.actorType === "user" ? "Board" : "Agent",
+              companyId: project.companyId,
+            },
+            issue: null,
+            workspace: {
+              baseCwd: workspaceCwd,
+              source: "project_primary",
+              projectId: project.id,
+              workspaceId: workspace.id,
+              repoUrl: workspace.repoUrl,
+              repoRef: workspace.repoRef,
+              strategy: "project_primary",
+              cwd: workspaceCwd,
+              branchName: workspace.defaultRef ?? workspace.repoRef ?? null,
+              worktreePath: null,
+              warnings: [],
+              created: false,
+            },
+            command: workspaceCommand.rawConfig,
+            adapterEnv: {},
+            recorder,
+            metadata: {
+              action,
+              projectId: project.id,
+              projectWorkspaceId: workspace.id,
+              workspaceCommandId: workspaceCommand.id,
+            },
+          }).then((nestedOperation) => ({
+            status: "succeeded" as const,
+            exitCode: 0,
+            metadata: {
+              nestedOperationId: nestedOperation?.id ?? null,
+              runtimeServiceCount,
+            },
+          }));
+        }
+
         const onLog = async (stream: "stdout" | "stderr", chunk: string) => {
           if (stream === "stdout") stdout.push(chunk);
           else stderr.push(chunk);
@@ -318,6 +418,7 @@ export function projectRoutes(db: Db) {
           await stopRuntimeServicesForProjectWorkspace({
             db,
             projectWorkspaceId: workspace.id,
+            runtimeServiceId: selectedRuntimeServiceId,
           });
         }
 
@@ -347,15 +448,37 @@ export function projectRoutes(db: Db) {
             config: { workspaceRuntime: runtimeConfig },
             adapterEnv: {},
             onLog,
+            serviceIndex: selectedServiceIndex,
           });
           runtimeServiceCount = startedServices.length;
         } else {
-          runtimeServiceCount = 0;
+          runtimeServiceCount = selectedRuntimeServiceId ? Math.max(0, (workspace.runtimeServices?.length ?? 1) - 1) : 0;
         }
 
+        const currentDesiredState: "running" | "stopped" =
+          workspace.runtimeConfig?.desiredState
+          ?? ((workspace.runtimeServices ?? []).some((service) => service.status === "starting" || service.status === "running")
+            ? "running"
+            : "stopped");
+        const nextRuntimeState: {
+          desiredState: "running" | "stopped";
+          serviceStates: Record<string, "running" | "stopped"> | null | undefined;
+        } = selectedRuntimeServiceId && (selectedServiceIndex === undefined || selectedServiceIndex === null)
+          ? {
+              desiredState: currentDesiredState,
+              serviceStates: workspace.runtimeConfig?.serviceStates ?? null,
+            }
+          : buildWorkspaceRuntimeDesiredStatePatch({
+              config: { workspaceRuntime: runtimeConfig },
+              currentDesiredState,
+              currentServiceStates: workspace.runtimeConfig?.serviceStates ?? null,
+              action,
+              serviceIndex: selectedServiceIndex,
+            });
         await svc.updateWorkspace(project.id, workspace.id, {
           runtimeConfig: {
-            desiredState: action === "stop" ? "stopped" : "running",
+            desiredState: nextRuntimeState.desiredState,
+            serviceStates: nextRuntimeState.serviceStates,
           },
         });
 
@@ -371,6 +494,9 @@ export function projectRoutes(db: Db) {
                 : "Started project workspace runtime services.\n",
           metadata: {
             runtimeServiceCount,
+            workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+            runtimeServiceId: selectedRuntimeServiceId,
+            serviceIndex: selectedServiceIndex,
           },
         };
       },
@@ -389,6 +515,11 @@ export function projectRoutes(db: Db) {
       details: {
         projectWorkspaceId: workspace.id,
         runtimeServiceCount,
+        workspaceCommandId: workspaceCommand?.id ?? target.workspaceCommandId ?? null,
+        workspaceCommandKind: workspaceCommand?.kind ?? null,
+        workspaceCommandName: workspaceCommand?.name ?? null,
+        runtimeServiceId: selectedRuntimeServiceId,
+        serviceIndex: selectedServiceIndex,
       },
     });
 
@@ -396,7 +527,10 @@ export function projectRoutes(db: Db) {
       workspace: updatedWorkspace,
       operation,
     });
-  });
+  }
+
+  router.post("/projects/:id/workspaces/:workspaceId/runtime-services/:action", validate(workspaceRuntimeControlTargetSchema), handleProjectWorkspaceRuntimeCommand);
+  router.post("/projects/:id/workspaces/:workspaceId/runtime-commands/:action", validate(workspaceRuntimeControlTargetSchema), handleProjectWorkspaceRuntimeCommand);
 
   router.delete("/projects/:id/workspaces/:workspaceId", async (req, res) => {
     const id = req.params.id as string;

server/src/routes/sidebar-preferences.ts

@@ -0,0 +1,71 @@
+import { Router, type Request, type Response } from "express";
+import type { Db } from "@paperclipai/db";
+import { upsertSidebarOrderPreferenceSchema } from "@paperclipai/shared";
+import { validate } from "../middleware/validate.js";
+import { logActivity, sidebarPreferenceService } from "../services/index.js";
+import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
+
+function requireBoardUserId(req: Request, res: Response): string | null {
+  assertBoard(req);
+  if (!req.actor.userId) {
+    res.status(403).json({ error: "Board user context required" });
+    return null;
+  }
+  return req.actor.userId;
+}
+
+export function sidebarPreferenceRoutes(db: Db) {
+  const router = Router();
+  const svc = sidebarPreferenceService(db);
+
+  router.get("/sidebar-preferences/me", async (req, res) => {
+    const userId = requireBoardUserId(req, res);
+    if (!userId) return;
+    res.json(await svc.getCompanyOrder(userId));
+  });
+
+  router.put("/sidebar-preferences/me", validate(upsertSidebarOrderPreferenceSchema), async (req, res) => {
+    const userId = requireBoardUserId(req, res);
+    if (!userId) return;
+    res.json(await svc.upsertCompanyOrder(userId, req.body.orderedIds));
+  });
+
+  router.get("/companies/:companyId/sidebar-preferences/me", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const userId = requireBoardUserId(req, res);
+    if (!userId) return;
+    res.json(await svc.getProjectOrder(companyId, userId));
+  });
+
+  router.put(
+    "/companies/:companyId/sidebar-preferences/me",
+    validate(upsertSidebarOrderPreferenceSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      assertCompanyAccess(req, companyId);
+      const userId = requireBoardUserId(req, res);
+      if (!userId) return;
+
+      const result = await svc.upsertProjectOrder(companyId, userId, req.body.orderedIds);
+      const actor = getActorInfo(req);
+      await logActivity(db, {
+        companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "sidebar_preferences.project_order_updated",
+        entityType: "company",
+        entityId: companyId,
+        details: {
+          userId,
+          orderedIds: result.orderedIds,
+        },
+      });
+      res.json(result);
+    },
+  );
+
+  return router;
+}

server/src/services/execution-workspaces.ts

@@ -192,6 +192,11 @@ export function readExecutionWorkspaceConfig(metadata: Record<string, unknown> |
     cleanupCommand: readNullableString(raw.cleanupCommand),
     workspaceRuntime: cloneRecord(raw.workspaceRuntime),
     desiredState: raw.desiredState === "running" || raw.desiredState === "stopped" ? raw.desiredState : null,
+    serviceStates: isRecord(raw.serviceStates)
+      ? Object.fromEntries(
+          Object.entries(raw.serviceStates).filter(([, state]) => state === "running" || state === "stopped"),
+        ) as ExecutionWorkspaceConfig["serviceStates"]
+      : null,
   };
 
   const hasConfig = Object.values(config).some((value) => {
@@ -214,6 +219,7 @@ export function mergeExecutionWorkspaceConfig(
     cleanupCommand: null,
     workspaceRuntime: null,
     desiredState: null,
+    serviceStates: null,
   };
 
   if (patch === null) {
@@ -232,6 +238,14 @@ export function mergeExecutionWorkspaceConfig(
           ? patch.desiredState
           : null
         : current.desiredState,
+    serviceStates:
+      patch.serviceStates !== undefined && isRecord(patch.serviceStates)
+        ? Object.fromEntries(
+            Object.entries(patch.serviceStates).filter(([, state]) => state === "running" || state === "stopped"),
+          ) as ExecutionWorkspaceConfig["serviceStates"]
+        : patch.serviceStates !== undefined
+          ? null
+          : current.serviceStates,
   };
 
   const hasConfig = Object.values(nextConfig).some((value) => {
@@ -247,6 +261,7 @@ export function mergeExecutionWorkspaceConfig(
       cleanupCommand: nextConfig.cleanupCommand,
       workspaceRuntime: nextConfig.workspaceRuntime,
       desiredState: nextConfig.desiredState,
+      serviceStates: nextConfig.serviceStates ?? null,
     };
   } else {
     delete nextMetadata.config;

server/src/services/index.ts

@@ -19,6 +19,7 @@ export { financeService } from "./finance.js";
 export { heartbeatService } from "./heartbeat.js";
 export { dashboardService } from "./dashboard.js";
 export { sidebarBadgeService } from "./sidebar-badges.js";
+export { sidebarPreferenceService } from "./sidebar-preferences.js";
 export { inboxDismissalService } from "./inbox-dismissals.js";
 export { accessService } from "./access.js";
 export { boardAuthService } from "./board-auth.js";

server/src/services/project-workspace-runtime-config.ts

@@ -12,6 +12,13 @@ function readDesiredState(value: unknown): ProjectWorkspaceRuntimeConfig["desire
   return value === "running" || value === "stopped" ? value : null;
 }
 
+function readServiceStates(value: unknown): ProjectWorkspaceRuntimeConfig["serviceStates"] {
+  if (!isRecord(value)) return null;
+  const entries = Object.entries(value).filter(([, state]) => state === "running" || state === "stopped");
+  if (entries.length === 0) return null;
+  return Object.fromEntries(entries) as ProjectWorkspaceRuntimeConfig["serviceStates"];
+}
+
 export function readProjectWorkspaceRuntimeConfig(
   metadata: Record<string, unknown> | null | undefined,
 ): ProjectWorkspaceRuntimeConfig | null {
@@ -21,9 +28,10 @@ export function readProjectWorkspaceRuntimeConfig(
   const config: ProjectWorkspaceRuntimeConfig = {
     workspaceRuntime: cloneRecord(raw.workspaceRuntime),
     desiredState: readDesiredState(raw.desiredState),
+    serviceStates: readServiceStates(raw.serviceStates),
   };
 
-  const hasConfig = config.workspaceRuntime !== null || config.desiredState !== null;
+  const hasConfig = config.workspaceRuntime !== null || config.desiredState !== null || config.serviceStates !== null;
   return hasConfig ? config : null;
 }
 
@@ -35,6 +43,7 @@ export function mergeProjectWorkspaceRuntimeConfig(
   const current = readProjectWorkspaceRuntimeConfig(metadata) ?? {
     workspaceRuntime: null,
     desiredState: null,
+    serviceStates: null,
   };
 
   if (patch === null) {
@@ -47,9 +56,11 @@ export function mergeProjectWorkspaceRuntimeConfig(
       patch.workspaceRuntime !== undefined ? cloneRecord(patch.workspaceRuntime) : current.workspaceRuntime,
     desiredState:
       patch.desiredState !== undefined ? readDesiredState(patch.desiredState) : current.desiredState,
+    serviceStates:
+      patch.serviceStates !== undefined ? readServiceStates(patch.serviceStates) : current.serviceStates,
   };
 
-  if (nextConfig.workspaceRuntime === null && nextConfig.desiredState === null) {
+  if (nextConfig.workspaceRuntime === null && nextConfig.desiredState === null && nextConfig.serviceStates === null) {
     delete nextMetadata.runtimeConfig;
   } else {
     nextMetadata.runtimeConfig = nextConfig;

server/src/services/sidebar-preferences.ts

@@ -0,0 +1,97 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  companyUserSidebarPreferences,
+  userSidebarPreferences,
+} from "@paperclipai/db";
+import type { SidebarOrderPreference } from "@paperclipai/shared";
+
+function normalizeOrderedIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+
+  const orderedIds: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const trimmed = item.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    orderedIds.push(trimmed);
+  }
+  return orderedIds;
+}
+
+function toPreference(orderedIds: unknown, updatedAt: Date | null): SidebarOrderPreference {
+  return {
+    orderedIds: normalizeOrderedIds(orderedIds),
+    updatedAt,
+  };
+}
+
+export function sidebarPreferenceService(db: Db) {
+  return {
+    async getCompanyOrder(userId: string): Promise<SidebarOrderPreference> {
+      const row = await db.query.userSidebarPreferences.findFirst({
+        where: eq(userSidebarPreferences.userId, userId),
+      });
+      return toPreference(row?.companyOrder ?? [], row?.updatedAt ?? null);
+    },
+
+    async upsertCompanyOrder(userId: string, orderedIds: string[]): Promise<SidebarOrderPreference> {
+      const now = new Date();
+      const normalized = normalizeOrderedIds(orderedIds);
+      const [row] = await db
+        .insert(userSidebarPreferences)
+        .values({
+          userId,
+          companyOrder: normalized,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [userSidebarPreferences.userId],
+          set: {
+            companyOrder: normalized,
+            updatedAt: now,
+          },
+        })
+        .returning();
+      return toPreference(row?.companyOrder ?? normalized, row?.updatedAt ?? now);
+    },
+
+    async getProjectOrder(companyId: string, userId: string): Promise<SidebarOrderPreference> {
+      const row = await db.query.companyUserSidebarPreferences.findFirst({
+        where: and(
+          eq(companyUserSidebarPreferences.companyId, companyId),
+          eq(companyUserSidebarPreferences.userId, userId),
+        ),
+      });
+      return toPreference(row?.projectOrder ?? [], row?.updatedAt ?? null);
+    },
+
+    async upsertProjectOrder(
+      companyId: string,
+      userId: string,
+      orderedIds: string[],
+    ): Promise<SidebarOrderPreference> {
+      const now = new Date();
+      const normalized = normalizeOrderedIds(orderedIds);
+      const [row] = await db
+        .insert(companyUserSidebarPreferences)
+        .values({
+          companyId,
+          userId,
+          projectOrder: normalized,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [companyUserSidebarPreferences.companyId, companyUserSidebarPreferences.userId],
+          set: {
+            projectOrder: normalized,
+            updatedAt: now,
+          },
+        })
+        .returning();
+      return toPreference(row?.projectOrder ?? normalized, row?.updatedAt ?? now);
+    },
+  };
+}

server/src/services/workspace-runtime.ts

@@ -8,6 +8,11 @@ import { setTimeout as delay } from "node:timers/promises";
 import type { AdapterRuntimeServiceReport } from "@paperclipai/adapter-utils";
 import type { Db } from "@paperclipai/db";
 import { executionWorkspaces, projectWorkspaces, workspaceRuntimeServices } from "@paperclipai/db";
+import {
+  listWorkspaceServiceCommandDefinitions,
+  type WorkspaceRuntimeDesiredState,
+  type WorkspaceRuntimeServiceStateMap,
+} from "@paperclipai/shared";
 import { and, desc, eq, inArray } from "drizzle-orm";
 import { asNumber, asString, parseObject, renderTemplate } from "../adapters/utils.js";
 import { resolveHomeAwarePath } from "../home-paths.js";
@@ -26,7 +31,11 @@ import { readExecutionWorkspaceConfig } from "./execution-workspaces.js";
 import { readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 
 export function resolveShell(): string {
-  return process.env.SHELL?.trim() || (process.platform === "win32" ? "sh" : "/bin/sh");
+  const fallback = process.platform === "win32" ? "sh" : "/bin/sh";
+  const shell = process.env.SHELL?.trim();
+  if (!shell) return fallback;
+  if (path.isAbsolute(shell) && !existsSync(shell)) return fallback;
+  return shell;
 }
 
 export interface ExecutionWorkspaceInput {
@@ -604,6 +613,56 @@ async function directoryExists(value: string) {
   return fs.stat(value).then((stats) => stats.isDirectory()).catch(() => false);
 }
 
+async function listLinkedGitWorktreePaths(repoRoot: string): Promise<Set<string>> {
+  const output = await runGit(["worktree", "list", "--porcelain"], repoRoot);
+  const paths = new Set<string>();
+  for (const line of output.split("\n")) {
+    if (!line.startsWith("worktree ")) continue;
+    const worktree = line.slice("worktree ".length).trim();
+    if (!worktree) continue;
+    paths.add(path.resolve(worktree));
+  }
+  return paths;
+}
+
+async function validateLinkedGitWorktree(input: {
+  repoRoot: string;
+  worktreePath: string;
+  expectedBranchName: string | null;
+}): Promise<{ valid: true } | { valid: false; reason: string }> {
+  const resolvedWorktreePath = path.resolve(input.worktreePath);
+  const listedWorktrees = await listLinkedGitWorktreePaths(input.repoRoot);
+  if (!listedWorktrees.has(resolvedWorktreePath)) {
+    return {
+      valid: false,
+      reason: "path is not registered in `git worktree list`",
+    };
+  }
+
+  const worktreeTopLevel = await runGit(["rev-parse", "--show-toplevel"], resolvedWorktreePath).catch(() => null);
+  if (!worktreeTopLevel || path.resolve(worktreeTopLevel) !== resolvedWorktreePath) {
+    return {
+      valid: false,
+      reason: "git resolves this path to a different repository root",
+    };
+  }
+
+  if (input.expectedBranchName) {
+    const currentBranch = await runGit(
+      ["symbolic-ref", "--quiet", "--short", "HEAD"],
+      resolvedWorktreePath,
+    ).catch(() => null);
+    if (currentBranch !== input.expectedBranchName) {
+      return {
+        valid: false,
+        reason: `worktree HEAD is on "${currentBranch ?? "<detached>"}" instead of "${input.expectedBranchName}"`,
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
 function terminateChildProcess(child: ChildProcess) {
   if (!child.pid) return;
   if (process.platform !== "win32") {
@@ -777,13 +836,13 @@ async function recordWorkspaceCommandOperation(
 ) {
   if (!recorder) {
     await runWorkspaceCommand(input);
-    return;
+    return null;
   }
 
   let stdout = "";
   let stderr = "";
   let code: number | null = null;
-  await recorder.recordOperation({
+  const operation = await recorder.recordOperation({
     phase: input.phase,
     command: input.command,
     cwd: input.cwd,
@@ -818,7 +877,7 @@ async function recordWorkspaceCommandOperation(
     },
   });
 
-  if (code === 0) return;
+  if (code === 0) return operation;
 
   const details = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
   throw new Error(
@@ -1004,18 +1063,32 @@ export async function realizeExecutionWorkspace(input: {
     };
   }
 
+  async function validateReusableWorktree(reusablePath: string) {
+    return await validateLinkedGitWorktree({
+      repoRoot,
+      worktreePath: reusablePath,
+      expectedBranchName: branchName,
+    }).catch(() => null);
+  }
+
   const existingWorktree = await directoryExists(worktreePath);
-  if (existingWorktree && await isGitCheckout(worktreePath)) {
-    return await reuseExistingWorktree(worktreePath);
+  if (existingWorktree) {
+    const validation = await validateReusableWorktree(worktreePath);
+    if (validation?.valid) {
+      return await reuseExistingWorktree(worktreePath);
+    }
+    const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
+    throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a reusable git worktree${reason}.`);
   }
 
   const registeredBranchWorktree = await findRegisteredGitWorktreeByBranch(repoRoot, branchName);
-  if (registeredBranchWorktree && await isGitCheckout(registeredBranchWorktree)) {
-    return await reuseExistingWorktree(registeredBranchWorktree);
-  }
-
-  if (existingWorktree) {
-    throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a git worktree.`);
+  if (registeredBranchWorktree) {
+    const validation = await validateReusableWorktree(registeredBranchWorktree);
+    if (validation?.valid) {
+      return await reuseExistingWorktree(registeredBranchWorktree);
+    }
+    const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
+    throw new Error(`Registered worktree for branch "${branchName}" at "${registeredBranchWorktree}" is not reusable${reason}.`);
   }
 
   try {
@@ -1087,6 +1160,147 @@ export async function realizeExecutionWorkspace(input: {
   };
 }
 
+export async function ensurePersistedExecutionWorkspaceAvailable(input: {
+  base: ExecutionWorkspaceInput;
+  workspace: {
+    mode: string | null | undefined;
+    strategyType: string | null | undefined;
+    cwd: string | null | undefined;
+    providerRef: string | null | undefined;
+    projectId: string | null | undefined;
+    projectWorkspaceId: string | null | undefined;
+    repoUrl: string | null | undefined;
+    baseRef: string | null | undefined;
+    branchName: string | null | undefined;
+    config?: {
+      provisionCommand?: string | null;
+    } | null;
+  };
+  issue: ExecutionWorkspaceIssueRef | null;
+  agent: ExecutionWorkspaceAgentRef;
+  recorder?: WorkspaceOperationRecorder | null;
+}): Promise<RealizedExecutionWorkspace | null> {
+  const cwd = asString(input.workspace.cwd ?? input.workspace.providerRef, "").trim();
+  if (!cwd) return null;
+
+  const strategy = input.workspace.strategyType === "git_worktree" ? "git_worktree" : "project_primary";
+  const realized: RealizedExecutionWorkspace = {
+    baseCwd: input.base.baseCwd,
+    source: input.workspace.mode === "shared_workspace" ? "project_primary" : "task_session",
+    projectId: input.workspace.projectId ?? input.base.projectId,
+    workspaceId: input.workspace.projectWorkspaceId ?? input.base.workspaceId,
+    repoUrl: input.workspace.repoUrl ?? input.base.repoUrl,
+    repoRef: input.workspace.baseRef ?? input.base.repoRef,
+    strategy,
+    cwd,
+    branchName: input.workspace.branchName ?? null,
+    worktreePath: strategy === "git_worktree" ? (input.workspace.providerRef ?? cwd) : null,
+    warnings: [],
+    created: false,
+  };
+  const provisionCommand = asString(input.workspace.config?.provisionCommand, "").trim();
+
+  if (strategy !== "git_worktree") {
+    return realized;
+  }
+  if (await directoryExists(cwd)) {
+    if (provisionCommand) {
+      const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);
+      await provisionExecutionWorktree({
+        strategy: {
+          type: "git_worktree",
+          provisionCommand,
+        },
+        base: input.base,
+        repoRoot,
+        worktreePath: realized.worktreePath ?? cwd,
+        branchName: realized.branchName ?? "",
+        issue: input.issue,
+        agent: input.agent,
+        created: false,
+        recorder: input.recorder ?? null,
+      });
+    }
+    return realized;
+  }
+
+  const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);
+  const worktreePath = realized.worktreePath ?? cwd;
+  const branchName = asString(input.workspace.branchName, "").trim();
+  if (!branchName) {
+    throw new Error(`Execution workspace "${cwd}" is missing and cannot be restored because no branch name is recorded.`);
+  }
+
+  await fs.mkdir(path.dirname(worktreePath), { recursive: true });
+  await runGit(["worktree", "prune"], repoRoot).catch(() => {});
+
+  let created = false;
+  try {
+    await recordGitOperation(input.recorder, {
+      phase: "worktree_prepare",
+      args: ["worktree", "add", worktreePath, branchName],
+      cwd: repoRoot,
+      metadata: {
+        repoRoot,
+        worktreePath,
+        branchName,
+        baseRef: input.workspace.baseRef ?? input.base.repoRef ?? null,
+        created: false,
+        restored: true,
+      },
+      successMessage: `Reattached missing git worktree at ${worktreePath}\n`,
+      failureLabel: `git worktree add ${worktreePath}`,
+    });
+  } catch (error) {
+    if (
+      !gitErrorIncludes(error, "invalid reference")
+      && !gitErrorIncludes(error, "not a commit")
+      && !gitErrorIncludes(error, "unknown revision")
+    ) {
+      throw error;
+    }
+    const baseRef = input.workspace.baseRef ?? await detectDefaultBranch(repoRoot) ?? "HEAD";
+    await recordGitOperation(input.recorder, {
+      phase: "worktree_prepare",
+      args: ["worktree", "add", "-b", branchName, worktreePath, baseRef],
+      cwd: repoRoot,
+      metadata: {
+        repoRoot,
+        worktreePath,
+        branchName,
+        baseRef,
+        created: true,
+        restored: true,
+      },
+      successMessage: `Recreated missing git worktree at ${worktreePath}\n`,
+      failureLabel: `git worktree add ${worktreePath}`,
+    });
+    created = true;
+  }
+
+  await provisionExecutionWorktree({
+    strategy: {
+      type: "git_worktree",
+      ...(provisionCommand ? { provisionCommand } : {}),
+    },
+    base: input.base,
+    repoRoot,
+    worktreePath,
+    branchName,
+    issue: input.issue,
+    agent: input.agent,
+    created,
+    recorder: input.recorder ?? null,
+  });
+
+  return {
+    ...realized,
+    cwd: worktreePath,
+    worktreePath,
+    created,
+  };
+}
+
 export async function cleanupExecutionWorkspaceArtifacts(input: {
   workspace: {
     id: string;
@@ -1380,6 +1594,83 @@ function resolveRuntimeServiceReuseIdentity(input: {
   };
 }
 
+function resolveWorkspaceCommandExecution(input: {
+  command: Record<string, unknown>;
+  workspace: RealizedExecutionWorkspace;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  adapterEnv: Record<string, string>;
+}) {
+  const name =
+    asString(input.command.name, "")
+    || asString(input.command.label, "")
+    || asString(input.command.title, "")
+    || "workspace command";
+  const command = asString(input.command.command, "");
+  const templateData = buildTemplateData({
+    workspace: input.workspace,
+    agent: input.agent,
+    issue: input.issue,
+    adapterEnv: input.adapterEnv,
+    port: null,
+  });
+  const cwd = resolveConfiguredPath(
+    renderTemplate(asString(input.command.cwd, "."), templateData),
+    input.workspace.cwd,
+  );
+  const env = {
+    ...sanitizeRuntimeServiceBaseEnv(process.env),
+    ...input.adapterEnv,
+    ...renderRuntimeServiceEnv({
+      envConfig: parseObject(input.command.env),
+      templateData,
+    }),
+  } as Record<string, string>;
+
+  return {
+    name,
+    command,
+    cwd,
+    env,
+  };
+}
+
+export async function runWorkspaceJobForControl(input: {
+  actor: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  command: Record<string, unknown>;
+  adapterEnv?: Record<string, string>;
+  recorder?: WorkspaceOperationRecorder | null;
+  metadata?: Record<string, unknown> | null;
+}) {
+  const resolved = resolveWorkspaceCommandExecution({
+    command: input.command,
+    workspace: input.workspace,
+    agent: input.actor,
+    issue: input.issue,
+    adapterEnv: input.adapterEnv ?? {},
+  });
+  if (!resolved.command) {
+    throw new Error(`Workspace job "${resolved.name}" is missing command`);
+  }
+
+  await ensureServerWorkspaceLinksCurrent(resolved.cwd);
+  return await recordWorkspaceCommandOperation(input.recorder, {
+    phase: "workspace_provision",
+    command: resolved.command,
+    cwd: resolved.cwd,
+    env: resolved.env,
+    label: `Workspace job "${resolved.name}"`,
+    metadata: {
+      workspaceCommandKind: "job",
+      workspaceCommandName: resolved.name,
+      ...(input.metadata ?? {}),
+    },
+    successMessage: `Completed workspace job "${resolved.name}"\n`,
+  });
+}
+
 function resolveServiceScopeId(input: {
   service: Record<string, unknown>;
   workspace: RealizedExecutionWorkspace;
@@ -1406,6 +1697,21 @@ function resolveServiceScopeId(input: {
   return { scopeType: "run" as const, scopeId: input.runId };
 }
 
+function looksLikeWorkspaceDevServerCommand(command: string) {
+  const normalized = command.trim().toLowerCase();
+  if (!normalized) return false;
+  return /(?:^|\s)(?:pnpm|npm|yarn|bun)\s+(?:run\s+)?dev(?:\s|$)/.test(normalized);
+}
+
+export function resolveWorkspaceRuntimeReadinessTimeoutSec(service: Record<string, unknown>) {
+  const readiness = parseObject(service.readiness);
+  const explicitTimeoutSec = asNumber(readiness.timeoutSec, 0);
+  if (explicitTimeoutSec > 0) {
+    return Math.max(1, explicitTimeoutSec);
+  }
+  return looksLikeWorkspaceDevServerCommand(asString(service.command, "")) ? 90 : 30;
+}
+
 async function waitForReadiness(input: {
   service: Record<string, unknown>;
   url: string | null;
@@ -1413,7 +1719,7 @@ async function waitForReadiness(input: {
   const readiness = parseObject(input.service.readiness);
   const readinessType = asString(readiness.type, "");
   if (readinessType !== "http" || !input.url) return;
-  const timeoutSec = Math.max(1, asNumber(readiness.timeoutSec, 30));
+  const timeoutSec = resolveWorkspaceRuntimeReadinessTimeoutSec(input.service);
   const intervalMs = Math.max(100, asNumber(readiness.intervalMs, 500));
   const deadline = Date.now() + timeoutSec * 1000;
   let lastError = "service did not become ready";
@@ -1735,6 +2041,11 @@ async function startLocalRuntimeService(input: {
     detached: process.platform !== "win32",
     stdio: ["ignore", "pipe", "pipe"],
   });
+  const spawnErrorPromise = new Promise<never>((_, reject) => {
+    child.once("error", (err) => {
+      reject(err);
+    });
+  });
   let stderrExcerpt = "";
   let stdoutExcerpt = "";
   child.stdout?.on("data", async (chunk) => {
@@ -1749,7 +2060,10 @@ async function startLocalRuntimeService(input: {
   });
 
   try {
-    await waitForReadiness({ service: input.service, url });
+    await Promise.race([
+      waitForReadiness({ service: input.service, url }),
+      spawnErrorPromise,
+    ]);
   } catch (err) {
     terminateChildProcess(child);
     throw new Error(
@@ -1913,10 +2227,78 @@ function registerRuntimeService(db: Db | undefined, record: RuntimeServiceRecord
 }
 
 function readRuntimeServiceEntries(config: Record<string, unknown>) {
-  const runtime = parseObject(config.workspaceRuntime);
-  return Array.isArray(runtime.services)
-    ? runtime.services.filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
-    : [];
+  return listWorkspaceServiceCommandDefinitions(parseObject(config.workspaceRuntime))
+    .map((command) => command.rawConfig);
+}
+
+export function listConfiguredRuntimeServiceEntries(config: Record<string, unknown>) {
+  return readRuntimeServiceEntries(config);
+}
+
+function readConfiguredServiceStates(config: Record<string, unknown>) {
+  const raw = parseObject(config.serviceStates);
+  const states: WorkspaceRuntimeServiceStateMap = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === "running" || value === "stopped") {
+      states[key] = value;
+    }
+  }
+  return states;
+}
+
+export function buildWorkspaceRuntimeDesiredStatePatch(input: {
+  config: Record<string, unknown>;
+  currentDesiredState: WorkspaceRuntimeDesiredState | null;
+  currentServiceStates: WorkspaceRuntimeServiceStateMap | null | undefined;
+  action: "start" | "stop" | "restart";
+  serviceIndex?: number | null;
+}): {
+  desiredState: WorkspaceRuntimeDesiredState;
+  serviceStates: WorkspaceRuntimeServiceStateMap | null;
+} {
+  const configuredServices = listConfiguredRuntimeServiceEntries(input.config);
+  const fallbackState: WorkspaceRuntimeDesiredState = input.currentDesiredState === "running" ? "running" : "stopped";
+  const nextServiceStates: WorkspaceRuntimeServiceStateMap = {};
+
+  for (let index = 0; index < configuredServices.length; index += 1) {
+    nextServiceStates[String(index)] = input.currentServiceStates?.[String(index)] ?? fallbackState;
+  }
+
+  const nextState: WorkspaceRuntimeDesiredState = input.action === "stop" ? "stopped" : "running";
+  if (input.serviceIndex === undefined || input.serviceIndex === null) {
+    for (let index = 0; index < configuredServices.length; index += 1) {
+      nextServiceStates[String(index)] = nextState;
+    }
+  } else if (input.serviceIndex >= 0 && input.serviceIndex < configuredServices.length) {
+    nextServiceStates[String(input.serviceIndex)] = nextState;
+  }
+
+  const desiredState = Object.values(nextServiceStates).some((state) => state === "running") ? "running" : "stopped";
+
+  return {
+    desiredState,
+    serviceStates: Object.keys(nextServiceStates).length > 0 ? nextServiceStates : null,
+  };
+}
+
+function selectRuntimeServiceEntries(input: {
+  config: Record<string, unknown>;
+  serviceIndex?: number | null;
+  respectDesiredStates?: boolean;
+  defaultDesiredState?: WorkspaceRuntimeDesiredState | null;
+  serviceStates?: WorkspaceRuntimeServiceStateMap | null;
+}) {
+  const entries = listConfiguredRuntimeServiceEntries(input.config);
+  const states = input.serviceStates ?? readConfiguredServiceStates(input.config);
+  const fallbackState: WorkspaceRuntimeDesiredState = input.defaultDesiredState === "running" ? "running" : "stopped";
+
+  return entries.filter((_, index) => {
+    if (input.serviceIndex !== undefined && input.serviceIndex !== null) {
+      return index === input.serviceIndex;
+    }
+    if (!input.respectDesiredStates) return true;
+    return (states[String(index)] ?? fallbackState) === "running";
+  });
 }
 
 export async function ensureRuntimeServicesForRun(input: {
@@ -2011,8 +2393,16 @@ export async function startRuntimeServicesForWorkspaceControl(input: {
   config: Record<string, unknown>;
   adapterEnv: Record<string, string>;
   onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+  serviceIndex?: number | null;
+  respectDesiredStates?: boolean;
 }): Promise<RuntimeServiceRef[]> {
-  const rawServices = readRuntimeServiceEntries(input.config);
+  const rawServices = selectRuntimeServiceEntries({
+    config: input.config,
+    serviceIndex: input.serviceIndex,
+    respectDesiredStates: input.respectDesiredStates,
+    defaultDesiredState: input.config.desiredState === "running" ? "running" : "stopped",
+    serviceStates: readConfiguredServiceStates(input.config),
+  });
   const refs: RuntimeServiceRef[] = [];
   const invocationId = input.invocationId ?? randomUUID();
 
@@ -2102,10 +2492,12 @@ export async function stopRuntimeServicesForExecutionWorkspace(input: {
   db?: Db;
   executionWorkspaceId: string;
   workspaceCwd?: string | null;
+  runtimeServiceId?: string | null;
 }) {
   const normalizedWorkspaceCwd = input.workspaceCwd ? path.resolve(input.workspaceCwd) : null;
   const matchingServiceIds = Array.from(runtimeServicesById.values())
     .filter((record) => {
+      if (input.runtimeServiceId) return record.id === input.runtimeServiceId;
       if (record.executionWorkspaceId === input.executionWorkspaceId) return true;
       if (!normalizedWorkspaceCwd || !record.cwd) return false;
       const resolvedCwd = path.resolve(record.cwd);
@@ -2121,19 +2513,37 @@ export async function stopRuntimeServicesForExecutionWorkspace(input: {
   }
 
   if (input.db) {
-    await markPersistedRuntimeServicesStoppedForExecutionWorkspace({
-      db: input.db,
-      executionWorkspaceId: input.executionWorkspaceId,
-    });
+    if (input.runtimeServiceId) {
+      const now = new Date();
+      await input.db
+        .update(workspaceRuntimeServices)
+        .set({
+          status: "stopped",
+          healthStatus: "unknown",
+          stoppedAt: now,
+          lastUsedAt: now,
+          updatedAt: now,
+        })
+        .where(eq(workspaceRuntimeServices.id, input.runtimeServiceId));
+    } else {
+      await markPersistedRuntimeServicesStoppedForExecutionWorkspace({
+        db: input.db,
+        executionWorkspaceId: input.executionWorkspaceId,
+      });
+    }
   }
 }
 
 export async function stopRuntimeServicesForProjectWorkspace(input: {
   db?: Db;
   projectWorkspaceId: string;
+  runtimeServiceId?: string | null;
 }) {
   const matchingServiceIds = Array.from(runtimeServicesById.values())
-    .filter((record) => record.projectWorkspaceId === input.projectWorkspaceId && record.scopeType === "project_workspace")
+    .filter((record) => {
+      if (input.runtimeServiceId) return record.id === input.runtimeServiceId;
+      return record.projectWorkspaceId === input.projectWorkspaceId && record.scopeType === "project_workspace";
+    })
     .map((record) => record.id);
 
   for (const serviceId of matchingServiceIds) {
@@ -2152,11 +2562,13 @@ export async function stopRuntimeServicesForProjectWorkspace(input: {
         updatedAt: now,
       })
       .where(
-        and(
-          eq(workspaceRuntimeServices.projectWorkspaceId, input.projectWorkspaceId),
-          eq(workspaceRuntimeServices.scopeType, "project_workspace"),
-          inArray(workspaceRuntimeServices.status, ["starting", "running"]),
-        ),
+        input.runtimeServiceId
+          ? eq(workspaceRuntimeServices.id, input.runtimeServiceId)
+          : and(
+              eq(workspaceRuntimeServices.projectWorkspaceId, input.projectWorkspaceId),
+              eq(workspaceRuntimeServices.scopeType, "project_workspace"),
+              inArray(workspaceRuntimeServices.status, ["starting", "running"]),
+            ),
       );
   }
 }
@@ -2292,6 +2704,7 @@ export async function restartDesiredRuntimeServicesOnStartup(db: Db) {
   const projectWorkspaceRows = await db
     .select()
     .from(projectWorkspaces);
+  const projectWorkspaceRowsById = new Map(projectWorkspaceRows.map((row) => [row.id, row] as const));
 
   for (const row of projectWorkspaceRows) {
     const runtimeConfig = readProjectWorkspaceRuntimeConfig((row.metadata as Record<string, unknown> | null) ?? null);
@@ -2316,8 +2729,13 @@ export async function restartDesiredRuntimeServicesOnStartup(db: Db) {
           warnings: [],
           created: false,
         },
-        config: { workspaceRuntime: runtimeConfig.workspaceRuntime },
+        config: {
+          workspaceRuntime: runtimeConfig.workspaceRuntime,
+          desiredState: runtimeConfig.desiredState,
+          serviceStates: runtimeConfig.serviceStates ?? null,
+        },
         adapterEnv: {},
+        respectDesiredStates: true,
       });
       if (refs.length > 0) restarted += refs.filter((ref) => !ref.reused).length;
     } catch {
@@ -2332,7 +2750,13 @@ export async function restartDesiredRuntimeServicesOnStartup(db: Db) {
 
   for (const row of executionWorkspaceRows) {
     const config = readExecutionWorkspaceConfig((row.metadata as Record<string, unknown> | null) ?? null);
-    if (config?.desiredState !== "running" || !config.workspaceRuntime || !row.cwd) continue;
+    const inheritedRuntimeConfig = row.projectWorkspaceId
+      ? readProjectWorkspaceRuntimeConfig(
+          (projectWorkspaceRowsById.get(row.projectWorkspaceId)?.metadata as Record<string, unknown> | null) ?? null,
+        )?.workspaceRuntime ?? null
+      : null;
+    const effectiveRuntimeConfig = config?.workspaceRuntime ?? inheritedRuntimeConfig;
+    if (config?.desiredState !== "running" || !effectiveRuntimeConfig || !row.cwd) continue;
 
     try {
       const refs = await startRuntimeServicesForWorkspaceControl({
@@ -2360,8 +2784,13 @@ export async function restartDesiredRuntimeServicesOnStartup(db: Db) {
           created: false,
         },
         executionWorkspaceId: row.id,
-        config: { workspaceRuntime: config.workspaceRuntime },
+        config: {
+          workspaceRuntime: effectiveRuntimeConfig,
+          desiredState: config.desiredState,
+          serviceStates: config.serviceStates ?? null,
+        },
         adapterEnv: {},
+        respectDesiredStates: true,
       });
       if (refs.length > 0) restarted += refs.filter((ref) => !ref.reused).length;
     } catch {

ui/src/App.tsx

@@ -162,6 +162,7 @@ function boardRoutes() {
       <Route path="routines/:routineId" element={<RoutineDetail />} />
       <Route path="execution-workspaces/:workspaceId" element={<ExecutionWorkspaceDetail />} />
       <Route path="execution-workspaces/:workspaceId/configuration" element={<ExecutionWorkspaceDetail />} />
+      <Route path="execution-workspaces/:workspaceId/runtime-logs" element={<ExecutionWorkspaceDetail />} />
       <Route path="execution-workspaces/:workspaceId/issues" element={<ExecutionWorkspaceDetail />} />
       <Route path="goals" element={<Goals />} />
       <Route path="goals/:goalId" element={<GoalDetail />} />
@@ -352,6 +353,7 @@ export function App() {
           <Route path="projects/:projectId/configuration" element={<UnprefixedBoardRedirect />} />
           <Route path="execution-workspaces/:workspaceId" element={<UnprefixedBoardRedirect />} />
           <Route path="execution-workspaces/:workspaceId/configuration" element={<UnprefixedBoardRedirect />} />
+          <Route path="execution-workspaces/:workspaceId/runtime-logs" element={<UnprefixedBoardRedirect />} />
           <Route path="execution-workspaces/:workspaceId/issues" element={<UnprefixedBoardRedirect />} />
           <Route path="tests/ux/chat" element={<UnprefixedBoardRedirect />} />
           <Route path="tests/ux/runs" element={<UnprefixedBoardRedirect />} />

ui/src/api/execution-workspaces.ts

@@ -1,5 +1,11 @@
-import type { ExecutionWorkspace, ExecutionWorkspaceCloseReadiness, WorkspaceOperation } from "@paperclipai/shared";
+import type {
+  ExecutionWorkspace,
+  ExecutionWorkspaceCloseReadiness,
+  WorkspaceOperation,
+  WorkspaceRuntimeControlTarget,
+} from "@paperclipai/shared";
 import { api } from "./client";
+import { sanitizeWorkspaceRuntimeControlTarget } from "./workspace-runtime-control";
 
 export const executionWorkspacesApi = {
   list: (
@@ -26,10 +32,23 @@ export const executionWorkspacesApi = {
     api.get<ExecutionWorkspaceCloseReadiness>(`/execution-workspaces/${id}/close-readiness`),
   listWorkspaceOperations: (id: string) =>
     api.get<WorkspaceOperation[]>(`/execution-workspaces/${id}/workspace-operations`),
-  controlRuntimeServices: (id: string, action: "start" | "stop" | "restart") =>
+  controlRuntimeServices: (
+    id: string,
+    action: "start" | "stop" | "restart",
+    target: WorkspaceRuntimeControlTarget = {},
+  ) =>
     api.post<{ workspace: ExecutionWorkspace; operation: WorkspaceOperation }>(
       `/execution-workspaces/${id}/runtime-services/${action}`,
-      {},
+      sanitizeWorkspaceRuntimeControlTarget(target),
+    ),
+  controlRuntimeCommands: (
+    id: string,
+    action: "start" | "stop" | "restart" | "run",
+    target: WorkspaceRuntimeControlTarget = {},
+  ) =>
+    api.post<{ workspace: ExecutionWorkspace; operation: WorkspaceOperation }>(
+      `/execution-workspaces/${id}/runtime-commands/${action}`,
+      sanitizeWorkspaceRuntimeControlTarget(target),
     ),
   update: (id: string, data: Record<string, unknown>) => api.patch<ExecutionWorkspace>(`/execution-workspaces/${id}`, data),
 };

ui/src/api/index.ts

@@ -15,5 +15,6 @@ export { dashboardApi } from "./dashboard";
 export { heartbeatsApi } from "./heartbeats";
 export { instanceSettingsApi } from "./instanceSettings";
 export { sidebarBadgesApi } from "./sidebarBadges";
+export { sidebarPreferencesApi } from "./sidebarPreferences";
 export { inboxDismissalsApi } from "./inboxDismissals";
 export { companySkillsApi } from "./companySkills";

ui/src/api/projects.ts

@@ -1,5 +1,11 @@
-import type { Project, ProjectWorkspace, WorkspaceOperation } from "@paperclipai/shared";
+import type {
+  Project,
+  ProjectWorkspace,
+  WorkspaceOperation,
+  WorkspaceRuntimeControlTarget,
+} from "@paperclipai/shared";
 import { api } from "./client";
+import { sanitizeWorkspaceRuntimeControlTarget } from "./workspace-runtime-control";
 
 function withCompanyScope(path: string, companyId?: string) {
   if (!companyId) return path;
@@ -32,10 +38,22 @@ export const projectsApi = {
     workspaceId: string,
     action: "start" | "stop" | "restart",
     companyId?: string,
+    target: WorkspaceRuntimeControlTarget = {},
   ) =>
     api.post<{ workspace: ProjectWorkspace; operation: WorkspaceOperation }>(
       projectPath(projectId, companyId, `/workspaces/${encodeURIComponent(workspaceId)}/runtime-services/${action}`),
-      {},
+      sanitizeWorkspaceRuntimeControlTarget(target),
+    ),
+  controlWorkspaceCommands: (
+    projectId: string,
+    workspaceId: string,
+    action: "start" | "stop" | "restart" | "run",
+    companyId?: string,
+    target: WorkspaceRuntimeControlTarget = {},
+  ) =>
+    api.post<{ workspace: ProjectWorkspace; operation: WorkspaceOperation }>(
+      projectPath(projectId, companyId, `/workspaces/${encodeURIComponent(workspaceId)}/runtime-commands/${action}`),
+      sanitizeWorkspaceRuntimeControlTarget(target),
     ),
   removeWorkspace: (projectId: string, workspaceId: string, companyId?: string) =>
     api.delete<ProjectWorkspace>(projectPath(projectId, companyId, `/workspaces/${encodeURIComponent(workspaceId)}`)),

ui/src/api/sidebarPreferences.ts

@@ -0,0 +1,12 @@
+import type { SidebarOrderPreference, UpsertSidebarOrderPreference } from "@paperclipai/shared";
+import { api } from "./client";
+
+export const sidebarPreferencesApi = {
+  getCompanyOrder: () => api.get<SidebarOrderPreference>("/sidebar-preferences/me"),
+  updateCompanyOrder: (data: UpsertSidebarOrderPreference) =>
+    api.put<SidebarOrderPreference>("/sidebar-preferences/me", data),
+  getProjectOrder: (companyId: string) =>
+    api.get<SidebarOrderPreference>(`/companies/${companyId}/sidebar-preferences/me`),
+  updateProjectOrder: (companyId: string, data: UpsertSidebarOrderPreference) =>
+    api.put<SidebarOrderPreference>(`/companies/${companyId}/sidebar-preferences/me`, data),
+};

ui/src/api/workspace-runtime-control.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { sanitizeWorkspaceRuntimeControlTarget } from "./workspace-runtime-control";
+
+describe("sanitizeWorkspaceRuntimeControlTarget", () => {
+  it("drops unexpected keys while preserving the selected runtime target", () => {
+    const sanitized = sanitizeWorkspaceRuntimeControlTarget({
+      workspaceCommandId: "web",
+      runtimeServiceId: "service-1",
+      serviceIndex: 2,
+      ...( { action: "start" } as Record<string, unknown> ),
+    });
+
+    expect(sanitized).toEqual({
+      workspaceCommandId: "web",
+      runtimeServiceId: "service-1",
+      serviceIndex: 2,
+    });
+    expect("action" in sanitized).toBe(false);
+  });
+
+  it("normalizes an omitted target to nullable fields", () => {
+    expect(sanitizeWorkspaceRuntimeControlTarget()).toEqual({
+      workspaceCommandId: null,
+      runtimeServiceId: null,
+      serviceIndex: null,
+    });
+  });
+});

ui/src/api/workspace-runtime-control.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceRuntimeControlTarget } from "@paperclipai/shared";
+
+export function sanitizeWorkspaceRuntimeControlTarget(
+  target: WorkspaceRuntimeControlTarget = {},
+): WorkspaceRuntimeControlTarget {
+  return {
+    workspaceCommandId: target.workspaceCommandId ?? null,
+    runtimeServiceId: target.runtimeServiceId ?? null,
+    serviceIndex: target.serviceIndex ?? null,
+  };
+}

ui/src/components/CompanyRail.tsx

@@ -1,6 +1,6 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useMemo } from "react";
 import { Paperclip, Plus } from "lucide-react";
-import { useQueries } from "@tanstack/react-query";
+import { useQueries, useQuery } from "@tanstack/react-query";
 import {
   DndContext,
   closestCenter,
@@ -22,6 +22,8 @@ import { cn } from "../lib/utils";
 import { queryKeys } from "../lib/queryKeys";
 import { sidebarBadgesApi } from "../api/sidebarBadges";
 import { heartbeatsApi } from "../api/heartbeats";
+import { authApi } from "../api/auth";
+import { useCompanyOrder } from "../hooks/useCompanyOrder";
 import { useLocation, useNavigate } from "@/lib/router";
 import {
   Tooltip,
@@ -31,42 +33,6 @@ import {
 import type { Company } from "@paperclipai/shared";
 import { CompanyPatternIcon } from "./CompanyPatternIcon";
 
-const ORDER_STORAGE_KEY = "paperclip.companyOrder";
-
-function getStoredOrder(): string[] {
-  try {
-    const raw = localStorage.getItem(ORDER_STORAGE_KEY);
-    if (raw) return JSON.parse(raw);
-  } catch { /* ignore */ }
-  return [];
-}
-
-function saveOrder(ids: string[]) {
-  localStorage.setItem(ORDER_STORAGE_KEY, JSON.stringify(ids));
-}
-
-/** Sort companies by stored order, appending any new ones at the end. */
-function sortByStoredOrder(companies: Company[]): Company[] {
-  const order = getStoredOrder();
-  if (order.length === 0) return companies;
-
-  const byId = new Map(companies.map((c) => [c.id, c]));
-  const sorted: Company[] = [];
-
-  for (const id of order) {
-    const c = byId.get(id);
-    if (c) {
-      sorted.push(c);
-      byId.delete(id);
-    }
-  }
-  // Append any companies not in stored order
-  for (const c of byId.values()) {
-    sorted.push(c);
-  }
-  return sorted;
-}
-
 function SortableCompanyItem({
   company,
   isSelected,
@@ -103,6 +69,10 @@ function SortableCompanyItem({
           <a
             href={`/${company.issuePrefix}/dashboard`}
             onClick={(e) => {
+              if (isDragging) {
+                e.preventDefault();
+                return;
+              }
               e.preventDefault();
               onSelect();
             }}
@@ -164,6 +134,11 @@ export function CompanyRail() {
     () => companies.filter((company) => company.status !== "archived"),
     [companies],
   );
+  const { data: session } = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+  });
+  const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;
   const companyIds = useMemo(() => sidebarCompanies.map((company) => company.id), [sidebarCompanies]);
 
   const liveRunsQueries = useQueries({
@@ -195,52 +170,10 @@ export function CompanyRail() {
     return result;
   }, [companyIds, sidebarBadgeQueries]);
 
-  // Maintain sorted order in local state, synced from companies + localStorage
-  const [orderedIds, setOrderedIds] = useState<string[]>(() =>
-    sortByStoredOrder(sidebarCompanies).map((c) => c.id)
-  );
-
-  // Re-sync orderedIds from localStorage whenever companies changes.
-  // Handles initial data load (companies starts as [] before query resolves)
-  // and subsequent refetches triggered by live updates.
-  useEffect(() => {
-    if (sidebarCompanies.length === 0) {
-      setOrderedIds([]);
-      return;
-    }
-    setOrderedIds(sortByStoredOrder(sidebarCompanies).map((c) => c.id));
-  }, [sidebarCompanies]);
-
-  // Sync order across tabs via the native storage event
-  useEffect(() => {
-    const handleStorage = (e: StorageEvent) => {
-      if (e.key !== ORDER_STORAGE_KEY) return;
-      try {
-        const ids: string[] = e.newValue ? JSON.parse(e.newValue) : [];
-        setOrderedIds(ids);
-      } catch { /* ignore malformed data */ }
-    };
-    window.addEventListener("storage", handleStorage);
-    return () => window.removeEventListener("storage", handleStorage);
-  }, []);
-
-  // Re-derive when companies change (new company added/removed)
-  const orderedCompanies = useMemo(() => {
-    const byId = new Map(sidebarCompanies.map((c) => [c.id, c]));
-    const result: Company[] = [];
-    for (const id of orderedIds) {
-      const c = byId.get(id);
-      if (c) {
-        result.push(c);
-        byId.delete(id);
-      }
-    }
-    // Append any new companies not yet in our order
-    for (const c of byId.values()) {
-      result.push(c);
-    }
-    return result;
-  }, [sidebarCompanies, orderedIds]);
+  const { orderedCompanies, persistOrder } = useCompanyOrder({
+    companies: sidebarCompanies,
+    userId: currentUserId,
+  });
 
   // Require 8px of movement before starting a drag to avoid interfering with clicks
   const sensors = useSensors(
@@ -260,11 +193,9 @@ export function CompanyRail() {
       const newIndex = ids.indexOf(over.id as string);
       if (oldIndex === -1 || newIndex === -1) return;
 
-      const newIds = arrayMove(ids, oldIndex, newIndex);
-      setOrderedIds(newIds);
-      saveOrder(newIds);
+      persistOrder(arrayMove(ids, oldIndex, newIndex));
     },
-    [orderedCompanies]
+    [orderedCompanies, persistOrder]
   );
 
   return (

ui/src/components/IssueFiltersPopover.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import type { ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { IssueFiltersPopover } from "./IssueFiltersPopover";
+import { defaultIssueFilterState } from "../lib/issue-filters";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("@/components/ui/popover", () => ({
+  Popover: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  PopoverTrigger: ({ children }: { children: ReactNode }) => <>{children}</>,
+  PopoverContent: ({ children, className }: { children: ReactNode; className?: string }) => (
+    <div data-testid="popover-content" className={className}>
+      {children}
+    </div>
+  ),
+}));
+
+vi.mock("@/components/ui/button", () => ({
+  Button: ({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  ),
+}));
+
+vi.mock("@/components/ui/checkbox", () => ({
+  Checkbox: ({ checked }: { checked?: boolean }) => <input type="checkbox" checked={checked} readOnly />,
+}));
+
+vi.mock("./StatusIcon", () => ({
+  StatusIcon: ({ status }: { status: string }) => <span>{status}</span>,
+}));
+
+vi.mock("./PriorityIcon", () => ({
+  PriorityIcon: ({ priority }: { priority: string }) => <span>{priority}</span>,
+}));
+
+describe("IssueFiltersPopover", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("uses a scrollable popover and a three-column desktop grid", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(
+        <IssueFiltersPopover
+          state={defaultIssueFilterState}
+          onChange={vi.fn()}
+          activeFilterCount={0}
+          agents={[{ id: "agent-1", name: "Agent One" }]}
+          projects={[{ id: "project-1", name: "Project One" }]}
+          labels={[{ id: "label-1", name: "Bug", color: "#ff0000" }]}
+          workspaces={[{ id: "workspace-1", name: "Workspace One" }]}
+          enableRoutineVisibilityFilter
+        />,
+      );
+    });
+
+    const popoverContent = container.querySelector("[data-testid='popover-content']");
+    expect(popoverContent).not.toBeNull();
+    expect(popoverContent?.className).toContain("overflow-y-auto");
+    expect(popoverContent?.className).toContain("max-h-[min(80vh,42rem)]");
+
+    const layoutGrid = Array.from(popoverContent?.querySelectorAll("div") ?? []).find((element) =>
+      element.className.includes("md:grid-cols-3"),
+    );
+    expect(layoutGrid?.className).toContain("grid-cols-1");
+  });
+});

ui/src/components/IssueFiltersPopover.tsx

@@ -80,7 +80,10 @@ export function IssueFiltersPopover({
           ) : null}
         </Button>
       </PopoverTrigger>
-      <PopoverContent align="end" className="w-[min(480px,calc(100vw-2rem))] p-0">
+      <PopoverContent
+        align="end"
+        className="w-[min(780px,calc(100vw-2rem))] max-h-[min(80vh,42rem)] overflow-y-auto overscroll-contain p-0"
+      >
         <div className="space-y-3 p-3">
           <div className="flex items-center justify-between">
             <span className="text-sm font-medium">Filters</span>
@@ -120,24 +123,24 @@ export function IssueFiltersPopover({
 
           <div className="border-t border-border" />
 
-          <div className="grid grid-cols-1 gap-x-4 gap-y-3 sm:grid-cols-2">
-            <div className="space-y-1">
-              <span className="text-xs text-muted-foreground">Status</span>
-              <div className="space-y-0.5">
-                {issueStatusOrder.map((status) => (
-                  <label key={status} className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50">
-                    <Checkbox
-                      checked={state.statuses.includes(status)}
-                      onCheckedChange={() => onChange({ statuses: toggleIssueFilterValue(state.statuses, status) })}
-                    />
-                    <StatusIcon status={status} />
-                    <span className="text-sm">{issueFilterLabel(status)}</span>
-                  </label>
-                ))}
+          <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
+            <div className="min-w-0 space-y-3">
+              <div className="space-y-1">
+                <span className="text-xs text-muted-foreground">Status</span>
+                <div className="space-y-0.5">
+                  {issueStatusOrder.map((status) => (
+                    <label key={status} className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50">
+                      <Checkbox
+                        checked={state.statuses.includes(status)}
+                        onCheckedChange={() => onChange({ statuses: toggleIssueFilterValue(state.statuses, status) })}
+                      />
+                      <StatusIcon status={status} />
+                      <span className="text-sm">{issueFilterLabel(status)}</span>
+                    </label>
+                  ))}
+                </div>
               </div>
-            </div>
 
-            <div className="space-y-3">
               <div className="space-y-1">
                 <span className="text-xs text-muted-foreground">Priority</span>
                 <div className="space-y-0.5">
@@ -153,7 +156,9 @@ export function IssueFiltersPopover({
                   ))}
                 </div>
               </div>
+            </div>
 
+            <div className="min-w-0 space-y-3">
               <div className="space-y-1">
                 <span className="text-xs text-muted-foreground">Assignee</span>
                 <div className="max-h-32 space-y-0.5 overflow-y-auto">
@@ -186,6 +191,25 @@ export function IssueFiltersPopover({
                 </div>
               </div>
 
+              {projects && projects.length > 0 ? (
+                <div className="space-y-1">
+                  <span className="text-xs text-muted-foreground">Project</span>
+                  <div className="max-h-32 space-y-0.5 overflow-y-auto">
+                    {projects.map((project) => (
+                      <label key={project.id} className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50">
+                        <Checkbox
+                          checked={state.projects.includes(project.id)}
+                          onCheckedChange={() => onChange({ projects: toggleIssueFilterValue(state.projects, project.id) })}
+                        />
+                        <span className="text-sm">{project.name}</span>
+                      </label>
+                    ))}
+                  </div>
+                </div>
+              ) : null}
+            </div>
+
+            <div className="min-w-0 space-y-3">
               {labels && labels.length > 0 ? (
                 <div className="space-y-1">
                   <span className="text-xs text-muted-foreground">Labels</span>
@@ -204,23 +228,6 @@ export function IssueFiltersPopover({
                 </div>
               ) : null}
 
-              {projects && projects.length > 0 ? (
-                <div className="space-y-1">
-                  <span className="text-xs text-muted-foreground">Project</span>
-                  <div className="max-h-32 space-y-0.5 overflow-y-auto">
-                    {projects.map((project) => (
-                      <label key={project.id} className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50">
-                        <Checkbox
-                          checked={state.projects.includes(project.id)}
-                          onCheckedChange={() => onChange({ projects: toggleIssueFilterValue(state.projects, project.id) })}
-                        />
-                        <span className="text-sm">{project.name}</span>
-                      </label>
-                    ))}
-                  </div>
-                </div>
-              ) : null}
-
               {workspaces && workspaces.length > 0 ? (
                 <div className="space-y-1">
                   <span className="text-xs text-muted-foreground">Workspace</span>

ui/src/components/IssueGroupHeader.tsx

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import { ChevronRight } from "lucide-react";
+import { cn } from "../lib/utils";
+
+type IssueGroupHeaderProps = {
+  label: string;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  onToggle?: () => void;
+  trailing?: ReactNode;
+  className?: string;
+};
+
+export function IssueGroupHeader({
+  label,
+  collapsible = false,
+  collapsed = false,
+  onToggle,
+  trailing,
+  className,
+}: IssueGroupHeaderProps) {
+  return (
+    <div className={cn("flex items-center py-1.5 pl-1 pr-3", className)}>
+      {collapsible ? (
+        <button
+          type="button"
+          className="flex min-w-0 items-center gap-1.5 text-left"
+          aria-expanded={!collapsed}
+          onClick={onToggle}
+        >
+          <ChevronRight
+            className={cn("h-3.5 w-3.5 shrink-0 text-muted-foreground transition-transform", !collapsed && "rotate-90")}
+          />
+          <span className="truncate text-sm font-semibold uppercase tracking-wide">
+            {label}
+          </span>
+        </button>
+      ) : (
+        <div className="flex min-w-0 items-center gap-1.5">
+          <span className="truncate text-sm font-semibold uppercase tracking-wide">
+            {label}
+          </span>
+        </div>
+      )}
+      {trailing ? <div className="ml-auto">{trailing}</div> : null}
+    </div>
+  );
+}

ui/src/components/IssuesList.test.tsx

@@ -351,8 +351,8 @@ describe("IssuesList", () => {
     });
   });
 
-  it("reuses the inbox issue column controls and persisted column visibility", async () => {
-    localStorage.setItem("paperclip:inbox:issue-columns", JSON.stringify(["id", "assignee"]));
+  it("uses context-scoped persisted column visibility", async () => {
+    localStorage.setItem("paperclip:test-issues:company-1:issue-columns", JSON.stringify(["id", "assignee"]));
 
     const assignedIssue = createIssue({
       id: "issue-assigned",
@@ -387,8 +387,41 @@ describe("IssuesList", () => {
     });
   });
 
+  it("preserves stored grouping across refresh when initial assignees are applied", async () => {
+    localStorage.setItem(
+      "paperclip:test-issues:company-1",
+      JSON.stringify({ groupBy: "status", sortField: "updated", sortDir: "desc" }),
+    );
+
+    const todoIssue = createIssue({ id: "issue-todo", title: "Alpha", status: "todo", assigneeAgentId: "agent-1" });
+    const doneIssue = createIssue({ id: "issue-done", title: "Beta", status: "done", assigneeAgentId: "agent-1" });
+
+    const { root } = renderWithQueryClient(
+      <IssuesList
+        issues={[todoIssue, doneIssue]}
+        agents={[{ id: "agent-1", name: "Agent One" }]}
+        projects={[]}
+        viewStateKey="paperclip:test-issues"
+        initialAssignees={["agent-1"]}
+        onUpdateIssue={() => undefined}
+      />,
+      container,
+    );
+
+    await waitForAssertion(() => {
+      expect(container.textContent).toContain("Todo");
+      expect(container.textContent).toContain("Done");
+      expect(container.textContent).toContain("Alpha");
+      expect(container.textContent).toContain("Beta");
+    });
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
   it("filters the list to a single workspace when a workspace name is clicked", async () => {
-    localStorage.setItem("paperclip:inbox:issue-columns", JSON.stringify(["id", "workspace"]));
+    localStorage.setItem("paperclip:test-issues:company-1:issue-columns", JSON.stringify(["id", "workspace"]));
     mockInstanceSettingsApi.getExperimental.mockResolvedValue({ enableIsolatedWorkspaces: true });
     mockExecutionWorkspacesApi.list.mockResolvedValue([
       {

ui/src/components/IssuesList.tsx

@@ -26,10 +26,8 @@ import {
 import {
   DEFAULT_INBOX_ISSUE_COLUMNS,
   getAvailableInboxIssueColumns,
-  loadInboxIssueColumns,
   normalizeInboxIssueColumns,
   resolveIssueWorkspaceName,
-  saveInboxIssueColumns,
   type InboxIssueColumn,
 } from "../lib/inbox";
 import { cn } from "../lib/utils";
@@ -43,13 +41,14 @@ import {
 import { StatusIcon } from "./StatusIcon";
 import { EmptyState } from "./EmptyState";
 import { Identity } from "./Identity";
+import { IssueGroupHeader } from "./IssueGroupHeader";
 import { IssueFiltersPopover } from "./IssueFiltersPopover";
 import { IssueRow } from "./IssueRow";
 import { PageSkeleton } from "./PageSkeleton";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover";
-import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@/components/ui/collapsible";
+import { Collapsible, CollapsibleContent } from "@/components/ui/collapsible";
 import { CircleDot, Plus, ArrowUpDown, Layers, Check, ChevronRight, List, ListTree, Columns3, User, Search } from "lucide-react";
 import { KanbanBoard } from "./KanbanBoard";
 import { buildIssueTree, countDescendants } from "../lib/issue-tree";
@@ -79,6 +78,7 @@ const defaultViewState: IssueViewState = {
   collapsedGroups: [],
   collapsedParents: [],
 };
+
 function getViewState(key: string): IssueViewState {
   try {
     const raw = localStorage.getItem(key);
@@ -91,6 +91,43 @@ function saveViewState(key: string, state: IssueViewState) {
   localStorage.setItem(key, JSON.stringify(state));
 }
 
+function getInitialViewState(key: string, initialAssignees?: string[]): IssueViewState {
+  const stored = getViewState(key);
+  if (!initialAssignees) return stored;
+  return {
+    ...stored,
+    assignees: initialAssignees,
+    statuses: [],
+  };
+}
+
+function getIssueColumnsStorageKey(key: string): string {
+  return `${key}:issue-columns`;
+}
+
+function loadIssueColumns(key: string): InboxIssueColumn[] {
+  try {
+    const raw = localStorage.getItem(getIssueColumnsStorageKey(key));
+    if (raw === null) return DEFAULT_INBOX_ISSUE_COLUMNS;
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return DEFAULT_INBOX_ISSUE_COLUMNS;
+    return normalizeInboxIssueColumns(parsed);
+  } catch {
+    return DEFAULT_INBOX_ISSUE_COLUMNS;
+  }
+}
+
+function saveIssueColumns(key: string, columns: InboxIssueColumn[]) {
+  try {
+    localStorage.setItem(
+      getIssueColumnsStorageKey(key),
+      JSON.stringify(normalizeInboxIssueColumns(columns)),
+    );
+  } catch {
+    // Ignore localStorage failures.
+  }
+}
+
 function sortIssues(issues: Issue[], state: IssueViewState): Issue[] {
   const sorted = [...issues];
   const dir = state.sortDir === "asc" ? 1 : -1;
@@ -240,17 +277,13 @@ export function IssuesList({
 
   // Scope the storage key per company so folding/view state is independent across companies.
   const scopedKey = selectedCompanyId ? `${viewStateKey}:${selectedCompanyId}` : viewStateKey;
+  const initialAssigneesKey = initialAssignees?.join("|") ?? "";
 
-  const [viewState, setViewState] = useState<IssueViewState>(() => {
-    if (initialAssignees) {
-      return { ...defaultViewState, assignees: initialAssignees, statuses: [] };
-    }
-    return getViewState(scopedKey);
-  });
+  const [viewState, setViewState] = useState<IssueViewState>(() => getInitialViewState(scopedKey, initialAssignees));
   const [assigneePickerIssueId, setAssigneePickerIssueId] = useState<string | null>(null);
   const [assigneeSearch, setAssigneeSearch] = useState("");
   const [issueSearch, setIssueSearch] = useState(initialSearch ?? "");
-  const [visibleIssueColumns, setVisibleIssueColumns] = useState<InboxIssueColumn[]>(loadInboxIssueColumns);
+  const [visibleIssueColumns, setVisibleIssueColumns] = useState<InboxIssueColumn[]>(() => loadIssueColumns(scopedKey));
   const deferredIssueSearch = useDeferredValue(issueSearch);
   const normalizedIssueSearch = deferredIssueSearch.trim().toLowerCase();
 
@@ -258,16 +291,23 @@ export function IssuesList({
     setIssueSearch(initialSearch ?? "");
   }, [initialSearch]);
 
-  // Reload view state from localStorage when company changes (scopedKey changes).
-  const prevScopedKey = useRef(scopedKey);
+  // Reload view state whenever the persisted context changes.
+  const prevViewStateContextKey = useRef(`${scopedKey}::${initialAssigneesKey}`);
   useEffect(() => {
-    if (prevScopedKey.current !== scopedKey) {
-      prevScopedKey.current = scopedKey;
-      setViewState(initialAssignees
-        ? { ...defaultViewState, assignees: initialAssignees, statuses: [] }
-        : getViewState(scopedKey));
+    const nextContextKey = `${scopedKey}::${initialAssigneesKey}`;
+    if (prevViewStateContextKey.current !== nextContextKey) {
+      prevViewStateContextKey.current = nextContextKey;
+      setViewState(getInitialViewState(scopedKey, initialAssignees));
     }
-  }, [scopedKey, initialAssignees]);
+  }, [scopedKey, initialAssignees, initialAssigneesKey]);
+
+  const prevColumnsScopedKey = useRef(scopedKey);
+  useEffect(() => {
+    if (prevColumnsScopedKey.current !== scopedKey) {
+      prevColumnsScopedKey.current = scopedKey;
+      setVisibleIssueColumns(loadIssueColumns(scopedKey));
+    }
+  }, [scopedKey]);
 
   const updateView = useCallback((patch: Partial<IssueViewState>) => {
     setViewState((prev) => {
@@ -521,8 +561,8 @@ export function IssuesList({
   const setIssueColumns = useCallback((next: InboxIssueColumn[]) => {
     const normalized = normalizeInboxIssueColumns(next);
     setVisibleIssueColumns(normalized);
-    saveInboxIssueColumns(normalized);
-  }, []);
+    saveIssueColumns(scopedKey, normalized);
+  }, [scopedKey]);
 
   const toggleIssueColumn = useCallback((column: InboxIssueColumn, enabled: boolean) => {
     if (enabled) {
@@ -723,22 +763,28 @@ export function IssuesList({
             }}
           >
             {group.label && (
-              <div className="flex items-center py-1.5 pl-1 pr-3">
-                <CollapsibleTrigger className="flex items-center gap-1.5">
-                  <ChevronRight className="h-3.5 w-3.5 shrink-0 text-muted-foreground transition-transform [[data-state=open]>&]:rotate-90" />
-                  <span className="text-sm font-semibold uppercase tracking-wide">
-                    {group.label}
-                  </span>
-                </CollapsibleTrigger>
-                <Button
-                  variant="ghost"
-                  size="icon-xs"
-                  className="ml-auto text-muted-foreground"
-                  onClick={() => openCreateIssueDialog(group.key)}
-                >
-                  <Plus className="h-3 w-3" />
-                </Button>
-              </div>
+              <IssueGroupHeader
+                label={group.label}
+                collapsible
+                collapsed={viewState.collapsedGroups.includes(group.key)}
+                onToggle={() => {
+                  updateView({
+                    collapsedGroups: viewState.collapsedGroups.includes(group.key)
+                      ? viewState.collapsedGroups.filter((k) => k !== group.key)
+                      : [...viewState.collapsedGroups, group.key],
+                  });
+                }}
+                trailing={(
+                  <Button
+                    variant="ghost"
+                    size="icon-xs"
+                    className="text-muted-foreground"
+                    onClick={() => openCreateIssueDialog(group.key)}
+                  >
+                    <Plus className="h-3 w-3" />
+                  </Button>
+                )}
+              />
             )}
             <CollapsibleContent>
               {(() => {

ui/src/components/ProjectWorkspaceSummaryCard.test.tsx

@@ -0,0 +1,192 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import type { ComponentProps, ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import type { ExecutionWorkspace, Issue } from "@paperclipai/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ProjectWorkspaceSummary } from "../lib/project-workspaces-tab";
+import { ProjectWorkspaceSummaryCard } from "./ProjectWorkspaceSummaryCard";
+
+vi.mock("@/lib/router", () => ({
+  Link: ({ children, to, ...props }: ComponentProps<"a"> & { to: string }) => <a href={to} {...props}>{children}</a>,
+}));
+
+vi.mock("./IssuesQuicklook", () => ({
+  IssuesQuicklook: ({ children }: { children: ReactNode }) => <>{children}</>,
+}));
+
+vi.mock("./CopyText", () => ({
+  CopyText: ({ children }: { children: ReactNode }) => <span>{children}</span>,
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createIssue(overrides: Partial<Issue> = {}): Issue {
+  return {
+    id: overrides.id ?? "issue-1",
+    companyId: overrides.companyId ?? "company-1",
+    projectId: overrides.projectId ?? "project-1",
+    projectWorkspaceId: overrides.projectWorkspaceId ?? null,
+    goalId: overrides.goalId ?? null,
+    parentId: overrides.parentId ?? null,
+    title: overrides.title ?? "Issue",
+    description: overrides.description ?? null,
+    status: overrides.status ?? "todo",
+    priority: overrides.priority ?? "medium",
+    assigneeAgentId: overrides.assigneeAgentId ?? null,
+    assigneeUserId: overrides.assigneeUserId ?? null,
+    checkoutRunId: overrides.checkoutRunId ?? null,
+    executionRunId: overrides.executionRunId ?? null,
+    executionAgentNameKey: overrides.executionAgentNameKey ?? null,
+    executionLockedAt: overrides.executionLockedAt ?? null,
+    createdByAgentId: overrides.createdByAgentId ?? null,
+    createdByUserId: overrides.createdByUserId ?? null,
+    issueNumber: overrides.issueNumber ?? 1,
+    identifier: overrides.identifier ?? "PAP-1",
+    requestDepth: overrides.requestDepth ?? 0,
+    billingCode: overrides.billingCode ?? null,
+    assigneeAdapterOverrides: overrides.assigneeAdapterOverrides ?? null,
+    executionWorkspaceId: overrides.executionWorkspaceId ?? null,
+    executionWorkspacePreference: overrides.executionWorkspacePreference ?? null,
+    executionWorkspaceSettings: overrides.executionWorkspaceSettings ?? null,
+    startedAt: overrides.startedAt ?? null,
+    completedAt: overrides.completedAt ?? null,
+    cancelledAt: overrides.cancelledAt ?? null,
+    hiddenAt: overrides.hiddenAt ?? null,
+    createdAt: overrides.createdAt ?? new Date("2026-04-12T00:00:00Z"),
+    updatedAt: overrides.updatedAt ?? new Date("2026-04-12T00:00:00Z"),
+  } as Issue;
+}
+
+function createSummary(overrides: Partial<ProjectWorkspaceSummary> = {}): ProjectWorkspaceSummary {
+  return {
+    key: overrides.key ?? "execution:workspace-1",
+    kind: overrides.kind ?? "execution_workspace",
+    workspaceId: overrides.workspaceId ?? "workspace-1",
+    workspaceName: overrides.workspaceName ?? "PAP-989-multi-user-implementation",
+    cwd: overrides.cwd ?? "/worktrees/PAP-989-multi-user-implementation",
+    branchName: overrides.branchName ?? "PAP-989-multi-user-implementation",
+    lastUpdatedAt: overrides.lastUpdatedAt ?? new Date("2026-04-12T00:00:00Z"),
+    projectWorkspaceId: overrides.projectWorkspaceId ?? "project-workspace-1",
+    executionWorkspaceId: overrides.executionWorkspaceId ?? "workspace-1",
+    executionWorkspaceStatus: overrides.executionWorkspaceStatus ?? "active",
+    serviceCount: overrides.serviceCount ?? 2,
+    runningServiceCount: overrides.runningServiceCount ?? 0,
+    primaryServiceUrl: overrides.primaryServiceUrl ?? "http://127.0.0.1:62474",
+    hasRuntimeConfig: overrides.hasRuntimeConfig ?? true,
+    issues: overrides.issues ?? [
+      createIssue({ id: "issue-1", identifier: "PAP-1364" }),
+      createIssue({ id: "issue-2", identifier: "PAP-1367" }),
+      createIssue({ id: "issue-3", identifier: "PAP-1362" }),
+      createIssue({ id: "issue-4", identifier: "PAP-1363" }),
+      createIssue({ id: "issue-5", identifier: "PAP-1340" }),
+    ],
+  };
+}
+
+describe("ProjectWorkspaceSummaryCard", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("renders a stacked mobile-friendly summary with metadata labels and compact issue pills", () => {
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <ProjectWorkspaceSummaryCard
+          projectRef="paperclip-app"
+          summary={createSummary()}
+          runtimeActionKey={null}
+          runtimeActionPending={false}
+          onRuntimeAction={() => {}}
+          onCloseWorkspace={() => {}}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain("Execution workspace");
+    expect(container.textContent).toContain("Branch");
+    expect(container.textContent).toContain("Path");
+    expect(container.textContent).toContain("Service");
+    expect(container.textContent).toContain("Linked issues");
+    expect(container.textContent).toContain("Start services");
+    expect(container.textContent).toContain("Close workspace");
+    expect(container.textContent).toContain("+1 more");
+
+    const actions = container.querySelector('[data-testid="workspace-summary-actions"]');
+    expect(actions?.className).toContain("flex-col");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("uses project workspace routes and omits close controls for project workspaces", () => {
+    const runtimeSpy = vi.fn();
+    const closeSpy = vi.fn();
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(
+        <ProjectWorkspaceSummaryCard
+          projectRef="paperclip-app"
+          summary={createSummary({
+            key: "project:workspace-2",
+            kind: "project_workspace",
+            executionWorkspaceId: null,
+            executionWorkspaceStatus: null,
+            hasRuntimeConfig: false,
+            issues: [createIssue({ id: "issue-6", identifier: "PAP-1400" })],
+          })}
+          runtimeActionKey={null}
+          runtimeActionPending={false}
+          onRuntimeAction={runtimeSpy}
+          onCloseWorkspace={closeSpy}
+        />,
+      );
+    });
+
+    const titleLink = container.querySelector("a[href='/projects/paperclip-app/workspaces/workspace-1']");
+    expect(titleLink).not.toBeNull();
+    expect(container.textContent).not.toContain("Close workspace");
+    expect(container.textContent).not.toContain("Start services");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("shows retry close for cleanup failures", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(
+        <ProjectWorkspaceSummaryCard
+          projectRef="paperclip-app"
+          summary={createSummary({
+            executionWorkspaceStatus: "cleanup_failed" as ExecutionWorkspace["status"],
+          })}
+          runtimeActionKey={null}
+          runtimeActionPending={false}
+          onRuntimeAction={() => {}}
+          onCloseWorkspace={() => {}}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain("Retry close");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});

ui/src/components/ProjectWorkspaceSummaryCard.tsx

@@ -0,0 +1,230 @@
+import { Link } from "@/lib/router";
+import type { ExecutionWorkspace, Issue } from "@paperclipai/shared";
+import { Button } from "@/components/ui/button";
+import { CopyText } from "./CopyText";
+import { IssuesQuicklook } from "./IssuesQuicklook";
+import type { ProjectWorkspaceSummary } from "../lib/project-workspaces-tab";
+import { cn, projectWorkspaceUrl } from "../lib/utils";
+import { timeAgo } from "../lib/timeAgo";
+import { Copy, ExternalLink, FolderOpen, GitBranch, Loader2, Play, Square } from "lucide-react";
+
+function workspaceKindLabel(kind: ProjectWorkspaceSummary["kind"]) {
+  return kind === "execution_workspace" ? "Execution workspace" : "Project workspace";
+}
+
+function truncatePath(path: string) {
+  const parts = path.split("/").filter(Boolean);
+  if (parts.length <= 3) return path;
+  return `…/${parts.slice(-3).join("/")}`;
+}
+
+interface ProjectWorkspaceSummaryCardProps {
+  projectRef: string;
+  summary: ProjectWorkspaceSummary;
+  runtimeActionKey: string | null;
+  runtimeActionPending: boolean;
+  onRuntimeAction: (input: {
+    key: string;
+    kind: "project_workspace" | "execution_workspace";
+    workspaceId: string;
+    action: "start" | "stop" | "restart";
+  }) => void;
+  onCloseWorkspace: (input: {
+    id: string;
+    name: string;
+    status: ExecutionWorkspace["status"];
+  }) => void;
+}
+
+export function ProjectWorkspaceSummaryCard({
+  projectRef,
+  summary,
+  runtimeActionKey,
+  runtimeActionPending,
+  onRuntimeAction,
+  onCloseWorkspace,
+}: ProjectWorkspaceSummaryCardProps) {
+  const visibleIssues = summary.issues.slice(0, 4);
+  const hiddenIssueCount = Math.max(summary.issues.length - visibleIssues.length, 0);
+  const workspaceHref =
+    summary.kind === "project_workspace"
+      ? projectWorkspaceUrl({ id: projectRef, urlKey: projectRef }, summary.workspaceId)
+      : `/execution-workspaces/${summary.workspaceId}`;
+  const hasRunningServices = summary.runningServiceCount > 0;
+  const actionKey = `${summary.key}:${hasRunningServices ? "stop" : "start"}`;
+
+  return (
+    <div className="border-b border-border px-4 py-4 last:border-b-0 sm:px-5">
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+          <div className="min-w-0 space-y-2">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="inline-flex items-center rounded-full border border-border bg-muted/25 px-2.5 py-1 text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
+                {workspaceKindLabel(summary.kind)}
+              </span>
+              <span className="inline-flex items-center rounded-full border border-border/70 bg-background px-2.5 py-1 text-xs text-muted-foreground">
+                Updated {timeAgo(summary.lastUpdatedAt)}
+              </span>
+              {summary.serviceCount > 0 ? (
+                <span
+                  className={cn(
+                    "inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs",
+                    hasRunningServices
+                      ? "border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300"
+                      : "border-border/70 bg-background text-muted-foreground",
+                  )}
+                >
+                  <span
+                    className={cn(
+                      "h-1.5 w-1.5 rounded-full",
+                      hasRunningServices ? "bg-emerald-500" : "bg-muted-foreground/40",
+                    )}
+                  />
+                  {summary.runningServiceCount}/{summary.serviceCount} services
+                </span>
+              ) : null}
+              {summary.executionWorkspaceStatus ? (
+                <span className="inline-flex items-center rounded-full border border-border/70 bg-background px-2.5 py-1 text-xs text-muted-foreground">
+                  {summary.executionWorkspaceStatus.replace(/_/g, " ")}
+                </span>
+              ) : null}
+            </div>
+            <Link
+              to={workspaceHref}
+              className="block break-words text-base font-semibold leading-6 text-foreground hover:underline"
+            >
+              {summary.workspaceName}
+            </Link>
+          </div>
+
+          <div
+            className="flex flex-col gap-2 min-[420px]:flex-row lg:w-auto lg:justify-end"
+            data-testid="workspace-summary-actions"
+          >
+            {summary.hasRuntimeConfig ? (
+              <Button
+                variant="outline"
+                size="sm"
+                className="h-9 justify-center px-3 text-xs"
+                disabled={runtimeActionPending}
+                onClick={() =>
+                  onRuntimeAction({
+                    key: summary.key,
+                    kind: summary.kind,
+                    workspaceId: summary.workspaceId,
+                    action: hasRunningServices ? "stop" : "start",
+                  })
+                }
+              >
+                {runtimeActionKey === actionKey ? (
+                  <Loader2 className="mr-2 h-3.5 w-3.5 animate-spin" />
+                ) : hasRunningServices ? (
+                  <Square className="mr-2 h-3.5 w-3.5" />
+                ) : (
+                  <Play className="mr-2 h-3.5 w-3.5" />
+                )}
+                {hasRunningServices ? "Stop services" : "Start services"}
+              </Button>
+            ) : null}
+            {summary.kind === "execution_workspace" && summary.executionWorkspaceId && summary.executionWorkspaceStatus ? (
+              <Button
+                variant="ghost"
+                size="sm"
+                className="h-9 px-3 text-xs text-muted-foreground"
+                onClick={() => onCloseWorkspace({
+                  id: summary.executionWorkspaceId!,
+                  name: summary.workspaceName,
+                  status: summary.executionWorkspaceStatus!,
+                })}
+              >
+                {summary.executionWorkspaceStatus === "cleanup_failed" ? "Retry close" : "Close workspace"}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+
+        <div className="rounded-xl border border-border/70 bg-muted/15 px-3 py-3">
+          <div className="space-y-2 text-sm">
+            {summary.branchName ? (
+              <div className="flex items-start gap-2">
+                <GitBranch className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                <div className="min-w-0">
+                  <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">Branch</div>
+                  <div className="break-all font-mono text-xs text-foreground">{summary.branchName}</div>
+                </div>
+              </div>
+            ) : null}
+
+            {summary.cwd ? (
+              <div className="flex items-start gap-2">
+                <FolderOpen className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                <div className="min-w-0 flex-1">
+                  <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">Path</div>
+                  <div className="flex items-start gap-2">
+                    <span className="min-w-0 break-all font-mono text-xs text-foreground" title={summary.cwd}>
+                      {truncatePath(summary.cwd)}
+                    </span>
+                    <CopyText text={summary.cwd} className="mt-0.5 shrink-0 text-muted-foreground hover:text-foreground" copiedLabel="Path copied">
+                      <Copy className="h-3.5 w-3.5" />
+                    </CopyText>
+                  </div>
+                </div>
+              </div>
+            ) : null}
+
+            {summary.primaryServiceUrl ? (
+              <div className="flex items-start gap-2">
+                <ExternalLink className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                <div className="min-w-0">
+                  <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground">Service</div>
+                  <a
+                    href={summary.primaryServiceUrl}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="break-all font-mono text-xs text-foreground hover:underline"
+                  >
+                    {summary.primaryServiceUrl}
+                  </a>
+                </div>
+              </div>
+            ) : null}
+          </div>
+        </div>
+
+        {summary.issues.length > 0 ? (
+          <div className="space-y-2">
+            <div className="text-[11px] font-medium uppercase tracking-[0.14em] text-muted-foreground">
+              Linked issues
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {visibleIssues.map((issue) => (
+                <IssuePill key={issue.id} issue={issue} />
+              ))}
+              {hiddenIssueCount > 0 ? (
+                <Link
+                  to={workspaceHref}
+                  className="inline-flex items-center rounded-full border border-border bg-background px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground hover:underline"
+                >
+                  +{hiddenIssueCount} more
+                </Link>
+              ) : null}
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function IssuePill({ issue }: { issue: Issue }) {
+  return (
+    <IssuesQuicklook issue={issue}>
+      <Link
+        to={`/issues/${issue.identifier ?? issue.id}`}
+        className="inline-flex items-center rounded-full border border-border bg-background px-2.5 py-1 font-mono text-xs text-foreground transition-colors hover:border-foreground/30 hover:text-foreground hover:underline"
+      >
+        {issue.identifier ?? issue.id.slice(0, 8)}
+      </Link>
+    </IssuesQuicklook>
+  );
+}

ui/src/components/SidebarProjects.tsx

@@ -76,7 +76,11 @@ function SortableProjectItem({
         <NavLink
           to={`/projects/${routeRef}/issues`}
           state={SIDEBAR_SCROLL_RESET_STATE}
-          onClick={() => {
+          onClick={(e) => {
+            if (isDragging) {
+              e.preventDefault();
+              return;
+            }
             if (isMobile) setSidebarOpen(false);
           }}
           className={cn(

ui/src/components/WorkspaceRuntimeControls.test.tsx

@@ -0,0 +1,269 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { WorkspaceRuntimeService } from "@paperclipai/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  buildWorkspaceRuntimeControlItems,
+  buildWorkspaceRuntimeControlSections,
+  WorkspaceRuntimeControls,
+} from "./WorkspaceRuntimeControls";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createRuntimeService(overrides: Partial<WorkspaceRuntimeService> = {}): WorkspaceRuntimeService {
+  return {
+    id: overrides.id ?? "service-1",
+    companyId: overrides.companyId ?? "company-1",
+    projectId: overrides.projectId ?? "project-1",
+    projectWorkspaceId: overrides.projectWorkspaceId ?? "workspace-1",
+    executionWorkspaceId: overrides.executionWorkspaceId ?? null,
+    issueId: overrides.issueId ?? null,
+    scopeType: overrides.scopeType ?? "project_workspace",
+    scopeId: overrides.scopeId ?? "workspace-1",
+    serviceName: overrides.serviceName ?? "web",
+    status: overrides.status ?? "stopped",
+    lifecycle: overrides.lifecycle ?? "shared",
+    reuseKey: overrides.reuseKey ?? null,
+    command: overrides.command ?? "pnpm dev",
+    cwd: overrides.cwd ?? "/repo",
+    port: overrides.port ?? null,
+    url: overrides.url ?? null,
+    provider: overrides.provider ?? "local_process",
+    providerRef: overrides.providerRef ?? null,
+    ownerAgentId: overrides.ownerAgentId ?? null,
+    startedByRunId: overrides.startedByRunId ?? null,
+    lastUsedAt: overrides.lastUsedAt ?? new Date("2026-04-12T00:00:00.000Z"),
+    startedAt: overrides.startedAt ?? new Date("2026-04-12T00:00:00.000Z"),
+    stoppedAt: overrides.stoppedAt ?? null,
+    stopPolicy: overrides.stopPolicy ?? null,
+    healthStatus: overrides.healthStatus ?? "unknown",
+    configIndex: overrides.configIndex ?? null,
+    createdAt: overrides.createdAt ?? new Date("2026-04-12T00:00:00.000Z"),
+    updatedAt: overrides.updatedAt ?? new Date("2026-04-12T00:00:00.000Z"),
+  };
+}
+
+describe("buildWorkspaceRuntimeControlSections", () => {
+  it("separates service and job commands while matching running services", () => {
+    const sections = buildWorkspaceRuntimeControlSections({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+          { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+        ],
+      },
+      runtimeServices: [
+        createRuntimeService({ id: "service-web", serviceName: "web", status: "running" }),
+      ],
+      canStartServices: true,
+      canRunJobs: true,
+    });
+
+    expect(sections.services).toHaveLength(1);
+    expect(sections.jobs).toHaveLength(1);
+    expect(sections.services[0]).toMatchObject({
+      title: "web",
+      statusLabel: "running",
+      workspaceCommandId: "web",
+      runtimeServiceId: "service-web",
+    });
+    expect(sections.jobs[0]).toMatchObject({
+      title: "db:migrate",
+      statusLabel: "run once",
+      workspaceCommandId: "db-migrate",
+    });
+  });
+});
+
+describe("buildWorkspaceRuntimeControlItems", () => {
+  it("keeps the legacy flat export shape for stale importers", () => {
+    const items = buildWorkspaceRuntimeControlItems({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+          { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+        ],
+      },
+      runtimeServices: [
+        createRuntimeService({ id: "service-web", serviceName: "web", status: "running" }),
+      ],
+      canStartServices: true,
+      canRunJobs: true,
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      title: "web",
+      status: "running",
+      statusLabel: "running",
+      runtimeServiceId: "service-web",
+    });
+  });
+});
+
+describe("WorkspaceRuntimeControls", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("renders service and job actions distinctly", () => {
+    const sections = buildWorkspaceRuntimeControlSections({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+          { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+        ],
+      },
+      runtimeServices: [
+        createRuntimeService({ id: "service-web", serviceName: "web", status: "running" }),
+      ],
+      canStartServices: true,
+      canRunJobs: true,
+    });
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <WorkspaceRuntimeControls
+          sections={sections}
+          onAction={vi.fn()}
+        />,
+      );
+    });
+
+    const buttons = Array.from(container.querySelectorAll("button")).map((button) => button.textContent?.trim());
+    expect(buttons).toEqual(["Stop", "Restart", "Run"]);
+    expect(container.textContent).toContain("Services");
+    expect(container.textContent).toContain("Jobs");
+
+    act(() => root.unmount());
+  });
+
+  it("shows disabled actions when local command prerequisites are missing", () => {
+    const sections = buildWorkspaceRuntimeControlSections({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+          { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+        ],
+      },
+      runtimeServices: [],
+      canStartServices: false,
+      canRunJobs: false,
+    });
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <WorkspaceRuntimeControls
+          sections={sections}
+          disabledHint="Add a workspace path first."
+          onAction={vi.fn()}
+        />,
+      );
+    });
+
+    const buttons = Array.from(container.querySelectorAll("button"));
+    expect(buttons.every((button) => button.hasAttribute("disabled"))).toBe(true);
+    expect(container.textContent).toContain("Add a workspace path first.");
+
+    act(() => root.unmount());
+  });
+
+  it("hides the disabled hint once services can already run", () => {
+    const sections = buildWorkspaceRuntimeControlSections({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+        ],
+      },
+      runtimeServices: [
+        createRuntimeService({ id: "service-web", serviceName: "web", status: "running" }),
+      ],
+      canStartServices: true,
+    });
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <WorkspaceRuntimeControls
+          sections={sections}
+          disabledHint="Add runtime settings first."
+          onAction={vi.fn()}
+        />,
+      );
+    });
+
+    expect(container.textContent).not.toContain("Add runtime settings first.");
+
+    act(() => root.unmount());
+  });
+
+  it("hides the health badge for stopped services", () => {
+    const sections = buildWorkspaceRuntimeControlSections({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+        ],
+      },
+      runtimeServices: [
+        createRuntimeService({ id: "service-web", serviceName: "web", status: "stopped", healthStatus: "unknown" }),
+      ],
+      canStartServices: true,
+    });
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <WorkspaceRuntimeControls
+          sections={sections}
+          onAction={vi.fn()}
+        />,
+      );
+    });
+
+    expect(container.textContent).not.toContain("unknown");
+
+    act(() => root.unmount());
+  });
+
+  it("accepts the legacy items prop without crashing", () => {
+    const items = buildWorkspaceRuntimeControlItems({
+      runtimeConfig: {
+        commands: [
+          { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+        ],
+      },
+      runtimeServices: [],
+      canStartServices: false,
+    });
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <WorkspaceRuntimeControls
+          items={items}
+          emptyMessage="No runtime services have been started yet."
+          disabledHint="Add runtime settings first."
+          onAction={vi.fn()}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain("Services");
+    expect(container.textContent).toContain("Add runtime settings first.");
+    expect(Array.from(container.querySelectorAll("button")).map((button) => button.textContent?.trim())).toEqual(["Start"]);
+
+    act(() => root.unmount());
+  });
+});

ui/src/components/WorkspaceRuntimeControls.tsx

@@ -0,0 +1,439 @@
+import type {
+  WorkspaceCommandDefinition,
+  WorkspaceRuntimeControlTarget,
+  WorkspaceRuntimeService,
+} from "@paperclipai/shared";
+import {
+  listWorkspaceCommandDefinitions,
+  matchWorkspaceRuntimeServiceToCommand,
+} from "@paperclipai/shared";
+import { Activity, ExternalLink, Loader2, Play, RotateCcw, Square } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+export type WorkspaceRuntimeAction = "start" | "stop" | "restart" | "run";
+
+export type WorkspaceRuntimeControlRequest = WorkspaceRuntimeControlTarget & {
+  action: WorkspaceRuntimeAction;
+};
+
+export type WorkspaceRuntimeControlItem = {
+  key: string;
+  title: string;
+  kind: "service" | "job";
+  statusLabel: string;
+  lifecycle: "shared" | "ephemeral" | null;
+  healthStatus: "unknown" | "healthy" | "unhealthy" | null;
+  command: string | null;
+  cwd: string | null;
+  port: number | null;
+  url: string | null;
+  canStart: boolean;
+  canRun: boolean;
+  workspaceCommandId?: string | null;
+  runtimeServiceId?: string | null;
+  serviceIndex?: number | null;
+  disabledReason?: string | null;
+};
+
+export type WorkspaceRuntimeControlSections = {
+  services: WorkspaceRuntimeControlItem[];
+  jobs: WorkspaceRuntimeControlItem[];
+  otherServices: WorkspaceRuntimeControlItem[];
+};
+
+type LegacyWorkspaceRuntimeControlItem = WorkspaceRuntimeControlItem & {
+  status?: string | null;
+};
+
+type WorkspaceRuntimeControlsProps = {
+  sections: WorkspaceRuntimeControlSections;
+  items?: never;
+  isPending?: boolean;
+  pendingRequest?: WorkspaceRuntimeControlRequest | null;
+  serviceEmptyMessage?: string;
+  jobEmptyMessage?: string;
+  emptyMessage?: never;
+  disabledHint?: string | null;
+  onAction: (request: WorkspaceRuntimeControlRequest) => void;
+  className?: string;
+} | {
+  sections?: never;
+  items: LegacyWorkspaceRuntimeControlItem[];
+  isPending?: boolean;
+  pendingRequest?: WorkspaceRuntimeControlRequest | null;
+  serviceEmptyMessage?: never;
+  jobEmptyMessage?: never;
+  emptyMessage?: string;
+  disabledHint?: string | null;
+  onAction: (request: WorkspaceRuntimeControlRequest) => void;
+  className?: string;
+};
+
+export function hasRunningRuntimeServices(
+  runtimeServices: Array<{ status: string }> | null | undefined,
+) {
+  return (runtimeServices ?? []).some((service) => service.status === "starting" || service.status === "running");
+}
+
+function buildServiceItem(
+  command: WorkspaceCommandDefinition,
+  runtimeService: WorkspaceRuntimeService | null,
+  canStartServices: boolean,
+): WorkspaceRuntimeControlItem {
+  return {
+    key: `command:${command.id}:${runtimeService?.id ?? "idle"}`,
+    title: command.name,
+    kind: "service",
+    statusLabel: runtimeService?.status ?? "stopped",
+    lifecycle: runtimeService?.lifecycle ?? command.lifecycle,
+    healthStatus: runtimeService?.healthStatus ?? "unknown",
+    command: runtimeService?.command ?? command.command,
+    cwd: runtimeService?.cwd ?? command.cwd,
+    port: runtimeService?.port ?? null,
+    url: runtimeService?.url ?? null,
+    canStart: canStartServices && !command.disabledReason,
+    canRun: false,
+    workspaceCommandId: command.id,
+    runtimeServiceId: runtimeService?.id ?? null,
+    serviceIndex: command.serviceIndex,
+    disabledReason: command.disabledReason,
+  };
+}
+
+function buildJobItem(
+  command: WorkspaceCommandDefinition,
+  canRunJobs: boolean,
+): WorkspaceRuntimeControlItem {
+  return {
+    key: `command:${command.id}`,
+    title: command.name,
+    kind: "job",
+    statusLabel: "run once",
+    lifecycle: null,
+    healthStatus: null,
+    command: command.command,
+    cwd: command.cwd,
+    port: null,
+    url: null,
+    canStart: false,
+    canRun: canRunJobs && !command.disabledReason && Boolean(command.command),
+    workspaceCommandId: command.id,
+    runtimeServiceId: null,
+    serviceIndex: null,
+    disabledReason: command.disabledReason ?? (!command.command ? "This job is missing a command." : null),
+  };
+}
+
+export function buildWorkspaceRuntimeControlSections(input: {
+  runtimeConfig: Record<string, unknown> | null | undefined;
+  runtimeServices: WorkspaceRuntimeService[] | null | undefined;
+  canStartServices: boolean;
+  canRunJobs?: boolean;
+}): WorkspaceRuntimeControlSections {
+  const commands = listWorkspaceCommandDefinitions(input.runtimeConfig);
+  const runtimeServices = [...(input.runtimeServices ?? [])];
+  const matchedRuntimeServiceIds = new Set<string>();
+  const services: WorkspaceRuntimeControlItem[] = [];
+  const jobs: WorkspaceRuntimeControlItem[] = [];
+
+  for (const command of commands) {
+    if (command.kind === "job") {
+      jobs.push(buildJobItem(command, input.canRunJobs ?? input.canStartServices));
+      continue;
+    }
+
+    const runtimeService = matchWorkspaceRuntimeServiceToCommand(command, runtimeServices);
+    if (runtimeService) matchedRuntimeServiceIds.add(runtimeService.id);
+    services.push(buildServiceItem(command, runtimeService, input.canStartServices));
+  }
+
+  const otherServices = runtimeServices
+    .filter((runtimeService) => !matchedRuntimeServiceIds.has(runtimeService.id))
+    .map((runtimeService) => ({
+      key: `runtime:${runtimeService.id}`,
+      title: runtimeService.serviceName,
+      kind: "service" as const,
+      statusLabel: runtimeService.status,
+      lifecycle: runtimeService.lifecycle,
+      healthStatus: runtimeService.healthStatus,
+      command: runtimeService.command ?? null,
+      cwd: runtimeService.cwd ?? null,
+      port: runtimeService.port ?? null,
+      url: runtimeService.url ?? null,
+      canStart: false,
+      canRun: false,
+      workspaceCommandId: null,
+      runtimeServiceId: runtimeService.id,
+      serviceIndex: runtimeService.configIndex ?? null,
+      disabledReason: "This runtime service no longer matches a configured workspace command.",
+    }));
+
+  return {
+    services,
+    jobs,
+    otherServices,
+  };
+}
+
+export function buildWorkspaceRuntimeControlItems(input: {
+  runtimeConfig: Record<string, unknown> | null | undefined;
+  runtimeServices: WorkspaceRuntimeService[] | null | undefined;
+  canStartServices: boolean;
+  canRunJobs?: boolean;
+}): LegacyWorkspaceRuntimeControlItem[] {
+  return buildWorkspaceRuntimeControlSections(input).services.map((item) => ({
+    ...item,
+    status: item.statusLabel,
+  }));
+}
+
+function requestMatchesPending(
+  pendingRequest: WorkspaceRuntimeControlRequest | null | undefined,
+  nextRequest: WorkspaceRuntimeControlRequest,
+) {
+  return pendingRequest?.action === nextRequest.action
+    && (pendingRequest?.workspaceCommandId ?? null) === (nextRequest.workspaceCommandId ?? null)
+    && (pendingRequest?.runtimeServiceId ?? null) === (nextRequest.runtimeServiceId ?? null)
+    && (pendingRequest?.serviceIndex ?? null) === (nextRequest.serviceIndex ?? null);
+}
+
+function buildRequest(item: WorkspaceRuntimeControlItem, action: WorkspaceRuntimeAction): WorkspaceRuntimeControlRequest {
+  return {
+    action,
+    workspaceCommandId: item.workspaceCommandId ?? null,
+    runtimeServiceId: item.runtimeServiceId ?? null,
+    serviceIndex: item.serviceIndex ?? null,
+  };
+}
+
+function CommandActionButtons({
+  item,
+  isPending,
+  pendingRequest,
+  onAction,
+}: {
+  item: WorkspaceRuntimeControlItem;
+  isPending: boolean;
+  pendingRequest: WorkspaceRuntimeControlRequest | null | undefined;
+  onAction: (request: WorkspaceRuntimeControlRequest) => void;
+}) {
+  const actions: WorkspaceRuntimeAction[] =
+    item.kind === "job"
+      ? ["run"]
+      : item.statusLabel === "running" || item.statusLabel === "starting"
+        ? ["stop", ...(item.canStart ? ["restart" as const] : [])]
+        : ["start"];
+
+  return (
+    <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:flex-wrap">
+      {actions.map((action) => {
+        const request = buildRequest(item, action);
+        const Icon = action === "stop" ? Square : action === "restart" ? RotateCcw : Play;
+        const label = action === "run"
+          ? "Run"
+          : action === "start"
+            ? "Start"
+            : action === "stop"
+              ? "Stop"
+              : "Restart";
+        const showSpinner = isPending && requestMatchesPending(pendingRequest, request);
+        const disabled =
+          isPending
+          || (action === "run" && !item.canRun)
+          || ((action === "start" || action === "restart") && !item.canStart);
+
+        return (
+          <Button
+            key={`${item.key}:${action}`}
+            variant={action === "stop" ? "destructive" : action === "restart" ? "outline" : "default"}
+            size="sm"
+            className={cn(
+              "h-9 w-full justify-start rounded-xl px-3 shadow-none sm:w-auto",
+              action === "restart" ? "bg-background" : null,
+            )}
+            disabled={disabled}
+            onClick={() => onAction(request)}
+          >
+            {showSpinner ? <Loader2 className="h-4 w-4 animate-spin" /> : <Icon className="h-4 w-4" />}
+            {label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}
+
+function CommandSection({
+  title,
+  description,
+  items,
+  emptyMessage,
+  disabledHint,
+  isPending,
+  pendingRequest,
+  onAction,
+}: {
+  title: string;
+  description: string;
+  items: WorkspaceRuntimeControlItem[];
+  emptyMessage: string;
+  disabledHint?: string | null;
+  isPending: boolean;
+  pendingRequest: WorkspaceRuntimeControlRequest | null | undefined;
+  onAction: (request: WorkspaceRuntimeControlRequest) => void;
+}) {
+  return (
+    <div className="space-y-3">
+      <div className="space-y-1">
+        <div className="text-sm font-medium">{title}</div>
+        <p className="text-xs text-muted-foreground">{description}</p>
+      </div>
+      {items.length === 0 ? (
+        <div className="rounded-xl border border-dashed border-border/80 bg-background/50 px-3 py-4 text-sm text-muted-foreground">
+          {emptyMessage}
+          {disabledHint ? <p className="mt-2 text-xs">{disabledHint}</p> : null}
+        </div>
+      ) : (
+        <div className="space-y-3">
+          {items.map((item) => (
+            <div key={item.key} className="rounded-xl border border-border/80 bg-background px-3 py-3">
+              <div className="flex flex-col gap-3">
+                <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                  <div className="space-y-1">
+                    <div className="text-sm font-medium">{item.title}</div>
+                    <div className="text-xs text-muted-foreground">
+                      {item.kind} · {item.statusLabel}
+                      {item.lifecycle ? ` · ${item.lifecycle}` : ""}
+                    </div>
+                  </div>
+                  <CommandActionButtons
+                    item={item}
+                    isPending={isPending}
+                    pendingRequest={pendingRequest}
+                    onAction={onAction}
+                  />
+                </div>
+                <div className="space-y-1 text-xs text-muted-foreground">
+                  {item.url ? (
+                    <a href={item.url} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 hover:underline">
+                      {item.url}
+                      <ExternalLink className="h-3.5 w-3.5" />
+                    </a>
+                  ) : null}
+                  {item.port ? <div>Port {item.port}</div> : null}
+                  {item.command ? <div className="break-all font-mono">{item.command}</div> : null}
+                  {item.cwd ? <div className="break-all font-mono">{item.cwd}</div> : null}
+                  {item.disabledReason ? <div>{item.disabledReason}</div> : null}
+                </div>
+                {item.healthStatus && item.statusLabel !== "stopped" ? (
+                  <div className="flex items-center gap-2">
+                    <span className={cn(
+                      "inline-flex items-center rounded-full border px-2.5 py-1 text-[11px]",
+                      item.healthStatus === "healthy"
+                        ? "border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300"
+                        : item.healthStatus === "unhealthy"
+                          ? "border-destructive/30 bg-destructive/10 text-destructive"
+                          : "border-border text-muted-foreground",
+                    )}>
+                      {item.healthStatus}
+                    </span>
+                  </div>
+                ) : null}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function WorkspaceRuntimeControls({
+  sections,
+  items,
+  isPending = false,
+  pendingRequest = null,
+  serviceEmptyMessage = "No services are configured for this workspace.",
+  jobEmptyMessage = "No one-shot jobs are configured for this workspace.",
+  emptyMessage,
+  disabledHint = null,
+  onAction,
+  className,
+}: WorkspaceRuntimeControlsProps) {
+  const resolvedSections = sections ?? {
+    services: (items ?? []).map((item) => ({
+      ...item,
+      statusLabel: item.statusLabel ?? item.status ?? "stopped",
+    })),
+    jobs: [],
+    otherServices: [],
+  };
+  const resolvedServiceEmptyMessage = emptyMessage ?? serviceEmptyMessage;
+  const runningCount = resolvedSections.services.filter(
+    (item) => item.statusLabel === "running" || item.statusLabel === "starting",
+  ).length;
+  const visibleDisabledHint = runningCount > 0 || disabledHint === null ? null : disabledHint;
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      <div className="rounded-xl border border-border/70 bg-background/60 p-3">
+        <div className="space-y-1">
+          <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Workspace commands</div>
+          <div className="flex flex-wrap items-center gap-2">
+            <span
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs font-medium",
+                runningCount > 0
+                  ? "border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300"
+                  : "border-border bg-background text-muted-foreground",
+              )}
+            >
+              <Activity className="h-3.5 w-3.5" />
+              {runningCount > 0 ? `${runningCount} services running` : "No services running"}
+            </span>
+            <span className="text-xs text-muted-foreground">
+              {resolvedSections.jobs.length > 0
+                ? `${resolvedSections.jobs.length} job${resolvedSections.jobs.length === 1 ? "" : "s"} available to run on demand.`
+                : "Each command can be controlled independently."}
+            </span>
+          </div>
+          {visibleDisabledHint ? <p className="text-xs text-muted-foreground">{visibleDisabledHint}</p> : null}
+        </div>
+      </div>
+
+      <CommandSection
+        title="Services"
+        description="Long-running commands that Paperclip can supervise for this workspace."
+        items={resolvedSections.services}
+        emptyMessage={resolvedServiceEmptyMessage}
+        disabledHint={visibleDisabledHint}
+        isPending={isPending}
+        pendingRequest={pendingRequest}
+        onAction={onAction}
+      />
+
+      <CommandSection
+        title="Jobs"
+        description="One-shot commands that run now and exit when they finish."
+        items={resolvedSections.jobs}
+        emptyMessage={jobEmptyMessage}
+        isPending={isPending}
+        pendingRequest={pendingRequest}
+        onAction={onAction}
+      />
+
+      {resolvedSections.otherServices.length > 0 ? (
+        <CommandSection
+          title="Untracked services"
+          description="Running services that no longer match the current workspace command config."
+          items={resolvedSections.otherServices}
+          emptyMessage=""
+          isPending={isPending}
+          pendingRequest={pendingRequest}
+          onAction={onAction}
+        />
+      ) : null}
+    </div>
+  );
+}

ui/src/hooks/useCompanyOrder.ts

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { Company } from "@paperclipai/shared";
+import { sidebarPreferencesApi } from "../api/sidebarPreferences";
+import { queryKeys } from "../lib/queryKeys";
+
+function areEqual(a: string[], b: string[]) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function sortCompaniesByOrder(companies: Company[], orderedIds: string[]): Company[] {
+  if (companies.length === 0) return [];
+  if (orderedIds.length === 0) return companies;
+
+  const byId = new Map(companies.map((company) => [company.id, company]));
+  const sorted: Company[] = [];
+
+  for (const id of orderedIds) {
+    const company = byId.get(id);
+    if (!company) continue;
+    sorted.push(company);
+    byId.delete(id);
+  }
+  for (const company of byId.values()) {
+    sorted.push(company);
+  }
+  return sorted;
+}
+
+function buildOrderIds(companies: Company[], orderedIds: string[]) {
+  return sortCompaniesByOrder(companies, orderedIds).map((company) => company.id);
+}
+
+type UseCompanyOrderParams = {
+  companies: Company[];
+  userId: string | null | undefined;
+};
+
+export function useCompanyOrder({ companies, userId }: UseCompanyOrderParams) {
+  const queryClient = useQueryClient();
+  const queryKey = useMemo(
+    () => queryKeys.sidebarPreferences.companyOrder(userId ?? "__anon__"),
+    [userId],
+  );
+
+  const { data } = useQuery({
+    queryKey,
+    queryFn: () => sidebarPreferencesApi.getCompanyOrder(),
+    enabled: Boolean(userId),
+  });
+
+  const [orderedIds, setOrderedIds] = useState<string[]>(() => buildOrderIds(companies, []));
+
+  useEffect(() => {
+    const nextIds = buildOrderIds(companies, data?.orderedIds ?? []);
+    setOrderedIds((current) => (areEqual(current, nextIds) ? current : nextIds));
+  }, [companies, data?.orderedIds]);
+
+  const mutation = useMutation({
+    mutationFn: (nextIds: string[]) => sidebarPreferencesApi.updateCompanyOrder({ orderedIds: nextIds }),
+    onSuccess: (preference) => {
+      queryClient.setQueryData(queryKey, preference);
+    },
+  });
+
+  const orderedCompanies = useMemo(
+    () => sortCompaniesByOrder(companies, orderedIds),
+    [companies, orderedIds],
+  );
+
+  const persistOrder = useCallback(
+    (ids: string[]) => {
+      const idSet = new Set(companies.map((company) => company.id));
+      const filtered = ids.filter((id) => idSet.has(id));
+      for (const company of companies) {
+        if (!filtered.includes(company.id)) filtered.push(company.id);
+      }
+
+      setOrderedIds((current) => (areEqual(current, filtered) ? current : filtered));
+      if (!userId) return;
+
+      queryClient.setQueryData(queryKey, (current: { orderedIds?: string[]; updatedAt?: Date | null } | undefined) => ({
+        orderedIds: filtered,
+        updatedAt: current?.updatedAt ?? null,
+      }));
+      mutation.mutate(filtered);
+    },
+    [companies, mutation, queryClient, queryKey, userId],
+  );
+
+  return {
+    orderedCompanies,
+    orderedIds,
+    persistOrder,
+  };
+}

ui/src/hooks/useProjectOrder.ts

@@ -1,12 +1,9 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { Project } from "@paperclipai/shared";
-import {
-  getProjectOrderStorageKey,
-  PROJECT_ORDER_UPDATED_EVENT,
-  readProjectOrder,
-  sortProjectsByStoredOrder,
-  writeProjectOrder,
-} from "../lib/project-order";
+import { sidebarPreferencesApi } from "../api/sidebarPreferences";
+import { sortProjectsByStoredOrder } from "../lib/project-order";
+import { queryKeys } from "../lib/queryKeys";
 
 type UseProjectOrderParams = {
   projects: Project[];
@@ -14,11 +11,6 @@ type UseProjectOrderParams = {
   userId: string | null | undefined;
 };
 
-type ProjectOrderUpdatedDetail = {
-  storageKey: string;
-  orderedIds: string[];
-};
-
 function areEqual(a: string[], b: string[]) {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i += 1) {
@@ -32,48 +24,33 @@ function buildOrderIds(projects: Project[], orderedIds: string[]) {
 }
 
 export function useProjectOrder({ projects, companyId, userId }: UseProjectOrderParams) {
-  const storageKey = useMemo(() => {
-    if (!companyId) return null;
-    return getProjectOrderStorageKey(companyId, userId);
-  }, [companyId, userId]);
+  const queryClient = useQueryClient();
+  const queryKey = useMemo(
+    () => queryKeys.sidebarPreferences.projectOrder(companyId ?? "__none__", userId ?? "__anon__"),
+    [companyId, userId],
+  );
+
+  const { data } = useQuery({
+    queryKey,
+    queryFn: () => sidebarPreferencesApi.getProjectOrder(companyId!),
+    enabled: Boolean(companyId && userId),
+  });
 
   const [orderedIds, setOrderedIds] = useState<string[]>(() => {
-    if (!storageKey) return projects.map((project) => project.id);
-    return buildOrderIds(projects, readProjectOrder(storageKey));
+    return buildOrderIds(projects, []);
   });
 
   useEffect(() => {
-    const nextIds = storageKey
-      ? buildOrderIds(projects, readProjectOrder(storageKey))
-      : projects.map((project) => project.id);
+    const nextIds = buildOrderIds(projects, data?.orderedIds ?? []);
     setOrderedIds((current) => (areEqual(current, nextIds) ? current : nextIds));
-  }, [projects, storageKey]);
+  }, [data?.orderedIds, projects]);
 
-  useEffect(() => {
-    if (!storageKey) return;
-
-    const syncFromIds = (ids: string[]) => {
-      const nextIds = buildOrderIds(projects, ids);
-      setOrderedIds((current) => (areEqual(current, nextIds) ? current : nextIds));
-    };
-
-    const onStorage = (event: StorageEvent) => {
-      if (event.key !== storageKey) return;
-      syncFromIds(readProjectOrder(storageKey));
-    };
-    const onCustomEvent = (event: Event) => {
-      const detail = (event as CustomEvent<ProjectOrderUpdatedDetail>).detail;
-      if (!detail || detail.storageKey !== storageKey) return;
-      syncFromIds(detail.orderedIds);
-    };
-
-    window.addEventListener("storage", onStorage);
-    window.addEventListener(PROJECT_ORDER_UPDATED_EVENT, onCustomEvent);
-    return () => {
-      window.removeEventListener("storage", onStorage);
-      window.removeEventListener(PROJECT_ORDER_UPDATED_EVENT, onCustomEvent);
-    };
-  }, [projects, storageKey]);
+  const mutation = useMutation({
+    mutationFn: (nextIds: string[]) => sidebarPreferencesApi.updateProjectOrder(companyId!, { orderedIds: nextIds }),
+    onSuccess: (preference) => {
+      queryClient.setQueryData(queryKey, preference);
+    },
+  });
 
   const orderedProjects = useMemo(
     () => sortProjectsByStoredOrder(projects, orderedIds),
@@ -89,11 +66,15 @@ export function useProjectOrder({ projects, companyId, userId }: UseProjectOrder
       }
 
       setOrderedIds((current) => (areEqual(current, filtered) ? current : filtered));
-      if (storageKey) {
-        writeProjectOrder(storageKey, filtered);
-      }
+      if (!companyId || !userId) return;
+
+      queryClient.setQueryData(queryKey, (current: { orderedIds?: string[]; updatedAt?: Date | null } | undefined) => ({
+        orderedIds: filtered,
+        updatedAt: current?.updatedAt ?? null,
+      }));
+      mutation.mutate(filtered);
     },
-    [projects, storageKey],
+    [companyId, mutation, projects, queryClient, queryKey, userId],
   );
 
   return {
@@ -102,4 +83,3 @@ export function useProjectOrder({ projects, companyId, userId }: UseProjectOrder
     persistOrder,
   };
 }
-

ui/src/lib/inbox.test.ts

@@ -12,11 +12,13 @@ import type {
 } from "@paperclipai/shared";
 import {
   DEFAULT_INBOX_ISSUE_COLUMNS,
+  buildInboxKeyboardNavEntries,
   buildInboxDismissedAtByKey,
   computeInboxBadgeData,
   filterInboxIssues,
   getArchivedInboxSearchIssues,
   getAvailableInboxIssueColumns,
+  getInboxWorkItemKey,
   getApprovalsForTab,
   getInboxWorkItems,
   getInboxKeyboardSelectionIndex,
@@ -28,16 +30,22 @@ import {
   isMineInboxTab,
   loadInboxFilterPreferences,
   loadInboxIssueColumns,
+  loadInboxWorkItemGroupBy,
+  loadCollapsedInboxGroupKeys,
   loadLastInboxTab,
   matchesInboxIssueSearch,
   normalizeInboxIssueColumns,
   RECENT_ISSUES_LIMIT,
   resolveInboxNestingEnabled,
   resolveIssueWorkspaceName,
+  resolveIssueWorkspaceGroup,
   resolveInboxSelectionIndex,
   saveInboxFilterPreferences,
+  saveCollapsedInboxGroupKeys,
   saveInboxIssueColumns,
+  saveInboxWorkItemGroupBy,
   saveLastInboxTab,
+  shouldResetInboxWorkspaceGrouping,
   shouldShowInboxSection,
   type InboxWorkItem,
 } from "./inbox";
@@ -487,6 +495,71 @@ describe("inbox helpers", () => {
     ]);
   });
 
+  it("skips hidden groups when building keyboard navigation entries", () => {
+    const visibleIssue = makeIssue("visible", true);
+    const hiddenIssue = makeIssue("hidden", true);
+    const approval = makeApprovalWithTimestamps("approval-1", "pending", "2026-03-11T03:00:00.000Z");
+
+    const entries = buildInboxKeyboardNavEntries(
+      [
+        {
+          key: "visible-group",
+          displayItems: [{ kind: "issue", timestamp: 3, issue: visibleIssue }],
+          childrenByIssueId: new Map(),
+        },
+        {
+          key: "hidden-group",
+          displayItems: [
+            { kind: "issue", timestamp: 2, issue: hiddenIssue },
+            { kind: "approval", timestamp: 1, approval },
+          ],
+          childrenByIssueId: new Map(),
+        },
+      ],
+      new Set(["hidden-group"]),
+      new Set(),
+    );
+
+    expect(entries).toEqual([
+      {
+        type: "top",
+        itemKey: `visible-group:${getInboxWorkItemKey({ kind: "issue", timestamp: 3, issue: visibleIssue })}`,
+        item: { kind: "issue", timestamp: 3, issue: visibleIssue },
+      },
+    ]);
+  });
+
+  it("includes child issues only when their parent row is expanded", () => {
+    const parentIssue = makeIssue("parent", true);
+    const childIssue = makeIssue("child", true);
+    childIssue.parentId = parentIssue.id;
+
+    const groupedSections = [
+      {
+        key: "workspace:default",
+        displayItems: [{ kind: "issue", timestamp: 2, issue: parentIssue } satisfies InboxWorkItem],
+        childrenByIssueId: new Map([[parentIssue.id, [childIssue]]]),
+      },
+    ];
+
+    expect(
+      buildInboxKeyboardNavEntries(groupedSections, new Set(), new Set()).map((entry) => entry.type === "top"
+        ? entry.itemKey
+        : entry.issueId),
+    ).toEqual([
+      `workspace:default:${getInboxWorkItemKey({ kind: "issue", timestamp: 2, issue: parentIssue })}`,
+      childIssue.id,
+    ]);
+
+    expect(
+      buildInboxKeyboardNavEntries(groupedSections, new Set(), new Set([parentIssue.id])).map((entry) => entry.type === "top"
+        ? entry.itemKey
+        : entry.issueId),
+    ).toEqual([
+      `workspace:default:${getInboxWorkItemKey({ kind: "issue", timestamp: 2, issue: parentIssue })}`,
+    ]);
+  });
+
   it("sorts self-touched issues without external comments by updatedAt", () => {
     const recentSelfTouched = makeIssue("recent", false);
     recentSelfTouched.lastExternalCommentAt = null as unknown as Date;
@@ -575,6 +648,22 @@ describe("inbox helpers", () => {
     )).toBe(true);
   });
 
+  it("resolves the default workspace into an explicit grouping label", () => {
+    const issue = makeIssue("default", false);
+    issue.projectId = "project-1";
+    issue.projectWorkspaceId = "project-workspace-1";
+
+    expect(resolveIssueWorkspaceGroup(issue, {
+      projectWorkspaceById: new Map([
+        ["project-workspace-1", { name: "Primary workspace" }],
+      ]),
+      defaultProjectWorkspaceIdByProjectId: new Map([["project-1", "project-workspace-1"]]),
+    })).toEqual({
+      key: "workspace:project:project-workspace-1",
+      label: "Primary workspace (default)",
+    });
+  });
+
   it("returns archived search matches that are not already visible in the inbox", () => {
     const visibleIssue = makeIssue("visible", false);
     visibleIssue.title = "Alpha visible task";
@@ -939,4 +1028,82 @@ describe("inbox helpers", () => {
       { key: "join_request", label: "Join requests", items: [items[4]] },
     ]);
   });
+
+  it("groups workspace sections by latest issue activity while preserving non-issue sections", () => {
+    const defaultIssue = makeIssue("default", true);
+    defaultIssue.projectId = "project-1";
+    defaultIssue.projectWorkspaceId = "project-workspace-1";
+
+    const sharedDefaultIssue = makeIssue("shared-default", true);
+    sharedDefaultIssue.projectId = "project-1";
+    sharedDefaultIssue.projectWorkspaceId = "project-workspace-1";
+    sharedDefaultIssue.executionWorkspaceId = "execution-workspace-shared-default";
+
+    const featureIssue = makeIssue("feature", false);
+    featureIssue.projectId = "project-1";
+    featureIssue.projectWorkspaceId = "project-workspace-2";
+
+    const execIssue = makeIssue("exec", false);
+    execIssue.projectId = "project-1";
+    execIssue.projectWorkspaceId = "project-workspace-1";
+    execIssue.executionWorkspaceId = "execution-workspace-1";
+
+    const items: InboxWorkItem[] = [
+      { kind: "issue", timestamp: 5, issue: defaultIssue },
+      { kind: "approval", timestamp: 2, approval: makeApproval("pending") },
+      { kind: "issue", timestamp: 4, issue: sharedDefaultIssue },
+      { kind: "issue", timestamp: 7, issue: featureIssue },
+      { kind: "issue", timestamp: 9, issue: execIssue },
+    ];
+
+    expect(groupInboxWorkItems(items, "workspace", {
+      executionWorkspaceById: new Map([
+        ["execution-workspace-1", { name: "Feature Branch", mode: "isolated_workspace", projectWorkspaceId: "project-workspace-1" }],
+        ["execution-workspace-shared-default", { name: "Shared default workspace", mode: "shared_workspace", projectWorkspaceId: "project-workspace-1" }],
+      ]),
+      projectWorkspaceById: new Map([
+        ["project-workspace-1", { name: "Primary workspace" }],
+        ["project-workspace-2", { name: "Secondary workspace" }],
+      ]),
+      defaultProjectWorkspaceIdByProjectId: new Map([["project-1", "project-workspace-1"]]),
+    })).toEqual([
+      { key: "workspace:execution:execution-workspace-1", label: "Feature Branch", items: [items[4]] },
+      { key: "workspace:project:project-workspace-2", label: "Secondary workspace", items: [items[3]] },
+      {
+        key: "workspace:project:project-workspace-1",
+        label: "Primary workspace (default)",
+        items: [items[0], items[2]],
+      },
+      { key: "kind:approval", label: "Approvals", items: [items[1]] },
+    ]);
+  });
+
+  it("persists workspace grouping preferences", () => {
+    saveInboxWorkItemGroupBy("workspace");
+    expect(loadInboxWorkItemGroupBy()).toBe("workspace");
+  });
+
+  it("persists collapsed inbox groups per company", () => {
+    saveCollapsedInboxGroupKeys("company-1", new Set(["workspace:alpha", "workspace:beta"]));
+    saveCollapsedInboxGroupKeys("company-2", new Set(["type:approval"]));
+
+    expect(loadCollapsedInboxGroupKeys("company-1")).toEqual(new Set(["workspace:alpha", "workspace:beta"]));
+    expect(loadCollapsedInboxGroupKeys("company-2")).toEqual(new Set(["type:approval"]));
+  });
+
+  it("returns empty collapsed inbox groups for missing or invalid storage", () => {
+    expect(loadCollapsedInboxGroupKeys("company-1")).toEqual(new Set());
+    localStorage.setItem("paperclip:inbox:collapsed-groups:company-1", JSON.stringify({ nope: true }));
+    expect(loadCollapsedInboxGroupKeys("company-1")).toEqual(new Set());
+  });
+
+  it("does not reset workspace grouping before experimental settings have loaded", () => {
+    expect(shouldResetInboxWorkspaceGrouping("workspace", false, false)).toBe(false);
+  });
+
+  it("resets workspace grouping only when settings are loaded and workspace grouping is unavailable", () => {
+    expect(shouldResetInboxWorkspaceGrouping("workspace", false, true)).toBe(true);
+    expect(shouldResetInboxWorkspaceGrouping("workspace", true, true)).toBe(false);
+    expect(shouldResetInboxWorkspaceGrouping("none", false, true)).toBe(false);
+  });
 });

ui/src/lib/inbox.ts

@@ -22,6 +22,7 @@ export const INBOX_ISSUE_COLUMNS_KEY = "paperclip:inbox:issue-columns";
 export const INBOX_NESTING_KEY = "paperclip:inbox:nesting";
 export const INBOX_GROUP_BY_KEY = "paperclip:inbox:group-by";
 export const INBOX_FILTER_PREFERENCES_KEY_PREFIX = "paperclip:inbox:filters";
+export const INBOX_COLLAPSED_GROUPS_KEY_PREFIX = "paperclip:inbox:collapsed-groups";
 export type InboxTab = "mine" | "recent" | "unread" | "all";
 export type InboxCategoryFilter =
   | "everything"
@@ -31,7 +32,7 @@ export type InboxCategoryFilter =
   | "failed_runs"
   | "alerts";
 export type InboxApprovalFilter = "all" | "actionable" | "resolved";
-export type InboxWorkItemGroupBy = "none" | "type";
+export type InboxWorkItemGroupBy = "none" | "type" | "workspace";
 export const inboxIssueColumns = [
   "status",
   "id",
@@ -86,6 +87,40 @@ export interface InboxWorkItemGroup {
   items: InboxWorkItem[];
 }
 
+export interface InboxKeyboardGroupSection {
+  key: string;
+  displayItems: InboxWorkItem[];
+  childrenByIssueId: ReadonlyMap<string, Issue[]>;
+}
+
+export type InboxKeyboardNavEntry =
+  | {
+      type: "top";
+      itemKey: string;
+      item: InboxWorkItem;
+    }
+  | {
+      type: "child";
+      issueId: string;
+      issue: Issue;
+    };
+
+export interface InboxProjectWorkspaceLookup {
+  name: string;
+}
+
+export interface InboxExecutionWorkspaceLookup {
+  name: string;
+  mode: "shared_workspace" | "isolated_workspace" | "operator_branch" | "adapter_managed" | "cloud_sandbox";
+  projectWorkspaceId: string | null;
+}
+
+export interface InboxWorkspaceGroupingOptions {
+  executionWorkspaceById?: ReadonlyMap<string, InboxExecutionWorkspaceLookup>;
+  projectWorkspaceById?: ReadonlyMap<string, InboxProjectWorkspaceLookup>;
+  defaultProjectWorkspaceIdByProjectId?: ReadonlyMap<string, string>;
+}
+
 const defaultInboxFilterPreferences: InboxFilterPreferences = {
   allCategoryFilter: "everything",
   allApprovalFilter: "all",
@@ -130,6 +165,11 @@ function getInboxFilterPreferencesStorageKey(companyId: string | null | undefine
   return `${INBOX_FILTER_PREFERENCES_KEY_PREFIX}:${companyId}`;
 }
 
+function getInboxCollapsedGroupsStorageKey(companyId: string | null | undefined): string | null {
+  if (!companyId) return null;
+  return `${INBOX_COLLAPSED_GROUPS_KEY_PREFIX}:${companyId}`;
+}
+
 export function loadInboxFilterPreferences(
   companyId: string | null | undefined,
 ): InboxFilterPreferences {
@@ -184,6 +224,36 @@ export function saveInboxFilterPreferences(
   }
 }
 
+export function loadCollapsedInboxGroupKeys(
+  companyId: string | null | undefined,
+): Set<string> {
+  const storageKey = getInboxCollapsedGroupsStorageKey(companyId);
+  if (!storageKey) return new Set();
+
+  try {
+    const raw = localStorage.getItem(storageKey);
+    if (!raw) return new Set();
+    const parsed = JSON.parse(raw);
+    return new Set(normalizeStringArray(parsed));
+  } catch {
+    return new Set();
+  }
+}
+
+export function saveCollapsedInboxGroupKeys(
+  companyId: string | null | undefined,
+  groupKeys: ReadonlySet<string>,
+) {
+  const storageKey = getInboxCollapsedGroupsStorageKey(companyId);
+  if (!storageKey) return;
+
+  try {
+    localStorage.setItem(storageKey, JSON.stringify([...groupKeys]));
+  } catch {
+    // Ignore localStorage failures.
+  }
+}
+
 export function loadDismissedInboxAlerts(): Set<string> {
   try {
     const raw = localStorage.getItem(DISMISSED_KEY);
@@ -273,7 +343,7 @@ export function saveInboxIssueColumns(columns: InboxIssueColumn[]) {
 export function loadInboxWorkItemGroupBy(): InboxWorkItemGroupBy {
   try {
     const raw = localStorage.getItem(INBOX_GROUP_BY_KEY);
-    return raw === "type" ? raw : "none";
+    return raw === "type" || raw === "workspace" ? raw : "none";
   } catch {
     return "none";
   }
@@ -287,6 +357,14 @@ export function saveInboxWorkItemGroupBy(groupBy: InboxWorkItemGroupBy) {
   }
 }
 
+export function shouldResetInboxWorkspaceGrouping(
+  groupBy: InboxWorkItemGroupBy,
+  isolatedWorkspacesEnabled: boolean,
+  experimentalSettingsLoaded: boolean,
+): boolean {
+  return experimentalSettingsLoaded && groupBy === "workspace" && !isolatedWorkspacesEnabled;
+}
+
 export function shouldIncludeRoutineExecutionIssue(
   issue: Pick<Issue, "originKind">,
   showRoutineExecutions: boolean,
@@ -307,15 +385,8 @@ export function matchesInboxIssueSearch(
     executionWorkspaceById,
     projectWorkspaceById,
     defaultProjectWorkspaceIdByProjectId,
-  }: {
+  }: InboxWorkspaceGroupingOptions & {
     isolatedWorkspacesEnabled?: boolean;
-    executionWorkspaceById?: ReadonlyMap<string, {
-      name: string;
-      mode: "shared_workspace" | "isolated_workspace" | "operator_branch" | "adapter_managed" | "cloud_sandbox";
-      projectWorkspaceId: string | null;
-    }>;
-    projectWorkspaceById?: ReadonlyMap<string, { name: string }>;
-    defaultProjectWorkspaceIdByProjectId?: ReadonlyMap<string, string>;
   } = {},
 ): boolean {
   const normalizedQuery = query.trim().toLowerCase();
@@ -346,12 +417,8 @@ export function getArchivedInboxSearchIssues({
   searchableIssues: Issue[];
   query: string;
   isolatedWorkspacesEnabled?: boolean;
-  executionWorkspaceById?: ReadonlyMap<string, {
-    name: string;
-    mode: "shared_workspace" | "isolated_workspace" | "operator_branch" | "adapter_managed" | "cloud_sandbox";
-    projectWorkspaceId: string | null;
-  }>;
-  projectWorkspaceById?: ReadonlyMap<string, { name: string }>;
+  executionWorkspaceById?: ReadonlyMap<string, InboxExecutionWorkspaceLookup>;
+  projectWorkspaceById?: ReadonlyMap<string, InboxProjectWorkspaceLookup>;
   defaultProjectWorkspaceIdByProjectId?: ReadonlyMap<string, string>;
 }): Issue[] {
   const normalizedQuery = query.trim();
@@ -400,21 +467,34 @@ export function getInboxSearchSupplementIssues({
     .filter((issue) => !visibleIssueIds.has(issue.id));
 }
 
+function formatDefaultWorkspaceGroupLabel(name: string | null | undefined): string {
+  const normalizedName = name?.trim();
+  return normalizedName ? `${normalizedName} (default)` : "Default workspace";
+}
+
+function resolveDefaultProjectWorkspaceInfo(
+  issue: Pick<Issue, "projectId">,
+  {
+    projectWorkspaceById,
+    defaultProjectWorkspaceIdByProjectId,
+  }: Pick<InboxWorkspaceGroupingOptions, "projectWorkspaceById" | "defaultProjectWorkspaceIdByProjectId">,
+): { id: string; label: string } | null {
+  if (!issue.projectId) return null;
+  const defaultProjectWorkspaceId = defaultProjectWorkspaceIdByProjectId?.get(issue.projectId) ?? null;
+  if (!defaultProjectWorkspaceId) return null;
+  return {
+    id: defaultProjectWorkspaceId,
+    label: formatDefaultWorkspaceGroupLabel(projectWorkspaceById?.get(defaultProjectWorkspaceId)?.name),
+  };
+}
+
 export function resolveIssueWorkspaceName(
   issue: Pick<Issue, "executionWorkspaceId" | "projectId" | "projectWorkspaceId">,
   {
     executionWorkspaceById,
     projectWorkspaceById,
     defaultProjectWorkspaceIdByProjectId,
-  }: {
-    executionWorkspaceById?: ReadonlyMap<string, {
-      name: string;
-      mode: "shared_workspace" | "isolated_workspace" | "operator_branch" | "adapter_managed" | "cloud_sandbox";
-      projectWorkspaceId: string | null;
-    }>;
-    projectWorkspaceById?: ReadonlyMap<string, { name: string }>;
-    defaultProjectWorkspaceIdByProjectId?: ReadonlyMap<string, string>;
-  },
+  }: InboxWorkspaceGroupingOptions,
 ): string | null {
   const defaultProjectWorkspaceId = issue.projectId
     ? defaultProjectWorkspaceIdByProjectId?.get(issue.projectId) ?? null
@@ -441,6 +521,74 @@ export function resolveIssueWorkspaceName(
   return null;
 }
 
+export function resolveIssueWorkspaceGroup(
+  issue: Pick<Issue, "executionWorkspaceId" | "projectId" | "projectWorkspaceId">,
+  {
+    executionWorkspaceById,
+    projectWorkspaceById,
+    defaultProjectWorkspaceIdByProjectId,
+  }: InboxWorkspaceGroupingOptions = {},
+): { key: string; label: string } {
+  const defaultProjectWorkspace = resolveDefaultProjectWorkspaceInfo(issue, {
+    projectWorkspaceById,
+    defaultProjectWorkspaceIdByProjectId,
+  });
+
+  if (issue.executionWorkspaceId) {
+    const executionWorkspace = executionWorkspaceById?.get(issue.executionWorkspaceId) ?? null;
+    const linkedProjectWorkspaceId =
+      executionWorkspace?.projectWorkspaceId ?? issue.projectWorkspaceId ?? null;
+    const isDefaultSharedExecutionWorkspace =
+      executionWorkspace?.mode === "shared_workspace"
+      && linkedProjectWorkspaceId != null
+      && linkedProjectWorkspaceId === defaultProjectWorkspace?.id;
+
+    if (isDefaultSharedExecutionWorkspace && defaultProjectWorkspace) {
+      return {
+        key: `workspace:project:${defaultProjectWorkspace.id}`,
+        label: defaultProjectWorkspace.label,
+      };
+    }
+
+    const workspaceName = executionWorkspace?.name?.trim();
+    if (workspaceName) {
+      return {
+        key: `workspace:execution:${issue.executionWorkspaceId}`,
+        label: workspaceName,
+      };
+    }
+  }
+
+  if (issue.projectWorkspaceId) {
+    if (issue.projectWorkspaceId === defaultProjectWorkspace?.id) {
+      return {
+        key: `workspace:project:${defaultProjectWorkspace.id}`,
+        label: defaultProjectWorkspace.label,
+      };
+    }
+
+    const workspaceName = projectWorkspaceById?.get(issue.projectWorkspaceId)?.name?.trim();
+    if (workspaceName) {
+      return {
+        key: `workspace:project:${issue.projectWorkspaceId}`,
+        label: workspaceName,
+      };
+    }
+  }
+
+  if (defaultProjectWorkspace) {
+    return {
+      key: `workspace:project:${defaultProjectWorkspace.id}`,
+      label: defaultProjectWorkspace.label,
+    };
+  }
+
+  return {
+    key: "workspace:none",
+    label: "No workspace",
+  };
+}
+
 export function loadInboxNesting(): boolean {
   try {
     const raw = localStorage.getItem(INBOX_NESTING_KEY);
@@ -642,11 +790,50 @@ const inboxWorkItemKindLabels: Record<InboxWorkItem["kind"], string> = {
 export function groupInboxWorkItems(
   items: InboxWorkItem[],
   groupBy: InboxWorkItemGroupBy,
+  options: InboxWorkspaceGroupingOptions = {},
 ): InboxWorkItemGroup[] {
   if (groupBy === "none") {
     return [{ key: "__all", label: null, items }];
   }
 
+  if (groupBy === "workspace") {
+    const groups = new Map<string, { label: string; items: InboxWorkItem[]; latestTimestamp: number }>();
+    for (const item of items) {
+      const resolvedGroup = item.kind === "issue"
+        ? resolveIssueWorkspaceGroup(item.issue, options)
+        : { key: `kind:${item.kind}`, label: inboxWorkItemKindLabels[item.kind] };
+      const existing = groups.get(resolvedGroup.key);
+      if (existing) {
+        existing.items.push(item);
+        existing.latestTimestamp = Math.max(existing.latestTimestamp, item.timestamp);
+      } else {
+        groups.set(resolvedGroup.key, {
+          label: resolvedGroup.label,
+          items: [item],
+          latestTimestamp: item.timestamp,
+        });
+      }
+    }
+
+    return [...groups.entries()]
+      .map(([key, value]) => ({
+        key,
+        label: value.label,
+        items: value.items,
+        latestTimestamp: value.latestTimestamp,
+      }))
+      .sort((a, b) => {
+        const timestampDiff = b.latestTimestamp - a.latestTimestamp;
+        if (timestampDiff !== 0) return timestampDiff;
+        return a.label.localeCompare(b.label);
+      })
+      .map(({ key, label, items: groupItems }) => ({
+        key,
+        label,
+        items: groupItems,
+      }));
+  }
+
   const groups = new Map<InboxWorkItem["kind"], InboxWorkItem[]>();
   for (const item of items) {
     const existing = groups.get(item.kind) ?? [];
@@ -729,6 +916,48 @@ export function buildInboxNesting(items: InboxWorkItem[]): {
   return { displayItems, childrenByIssueId };
 }
 
+export function getInboxWorkItemKey(item: InboxWorkItem): string {
+  if (item.kind === "issue") return `issue:${item.issue.id}`;
+  if (item.kind === "approval") return `approval:${item.approval.id}`;
+  if (item.kind === "failed_run") return `run:${item.run.id}`;
+  return `join:${item.joinRequest.id}`;
+}
+
+export function buildInboxKeyboardNavEntries(
+  groupedSections: ReadonlyArray<InboxKeyboardGroupSection>,
+  collapsedGroupKeys: ReadonlySet<string>,
+  collapsedInboxParents: ReadonlySet<string>,
+): InboxKeyboardNavEntry[] {
+  const entries: InboxKeyboardNavEntry[] = [];
+
+  for (const group of groupedSections) {
+    if (collapsedGroupKeys.has(group.key)) continue;
+
+    for (const item of group.displayItems) {
+      entries.push({
+        type: "top",
+        itemKey: `${group.key}:${getInboxWorkItemKey(item)}`,
+        item,
+      });
+
+      if (item.kind !== "issue") continue;
+
+      const children = group.childrenByIssueId.get(item.issue.id);
+      if (!children?.length || collapsedInboxParents.has(item.issue.id)) continue;
+
+      for (const child of children) {
+        entries.push({
+          type: "child",
+          issueId: child.id,
+          issue: child,
+        });
+      }
+    }
+  }
+
+  return entries;
+}
+
 export function shouldShowInboxSection({
   tab,
   hasItems,

ui/src/lib/keyboardShortcuts.test.ts

@@ -8,6 +8,7 @@ import {
   isKeyboardShortcutTextInputTarget,
   resolveIssueDetailGoKeyAction,
   resolveInboxQuickArchiveKeyAction,
+  resolveInboxUndoArchiveKeyAction,
   shouldBlurPageSearchOnEnter,
   shouldBlurPageSearchOnEscape,
 } from "./keyboardShortcuts";
@@ -181,6 +182,36 @@ describe("keyboardShortcuts helpers", () => {
     })).toBe("ignore");
   });
 
+  it("undoes only a clean lowercase u press when an archive is available", () => {
+    const button = document.createElement("button");
+
+    expect(resolveInboxUndoArchiveKeyAction({
+      hasUndoableArchive: true,
+      defaultPrevented: false,
+      key: "u",
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      target: button,
+      hasOpenDialog: false,
+    })).toBe("undo_archive");
+  });
+
+  it("keeps uppercase U available for mark-unread handling", () => {
+    const button = document.createElement("button");
+
+    expect(resolveInboxUndoArchiveKeyAction({
+      hasUndoableArchive: true,
+      defaultPrevented: false,
+      key: "U",
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      target: button,
+      hasOpenDialog: false,
+    })).toBe("ignore");
+  });
+
   it("arms go-to-inbox on a clean g press", () => {
     const button = document.createElement("button");
 

ui/src/lib/keyboardShortcuts.ts

@@ -12,6 +12,7 @@ const PAGE_SEARCH_SHORTCUT_SELECTOR = "[data-page-search-target='true']";
 const MODIFIER_ONLY_KEYS = new Set(["Shift", "Meta", "Control", "Alt"]);
 
 export type InboxQuickArchiveKeyAction = "ignore" | "archive" | "disarm";
+export type InboxUndoArchiveKeyAction = "ignore" | "undo_archive";
 export type IssueDetailGoKeyAction = "ignore" | "arm" | "navigate_inbox" | "focus_comment" | "disarm";
 
 export function isKeyboardShortcutTextInputTarget(target: EventTarget | null): boolean {
@@ -105,6 +106,33 @@ export function resolveInboxQuickArchiveKeyAction({
   return "ignore";
 }
 
+export function resolveInboxUndoArchiveKeyAction({
+  hasUndoableArchive,
+  defaultPrevented,
+  key,
+  metaKey,
+  ctrlKey,
+  altKey,
+  target,
+  hasOpenDialog,
+}: {
+  hasUndoableArchive: boolean;
+  defaultPrevented: boolean;
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  target: EventTarget | null;
+  hasOpenDialog: boolean;
+}): InboxUndoArchiveKeyAction {
+  if (!hasUndoableArchive) return "ignore";
+  if (defaultPrevented) return "ignore";
+  if (metaKey || ctrlKey || altKey || isModifierOnlyKey(key)) return "ignore";
+  if (hasOpenDialog || isKeyboardShortcutTextInputTarget(target)) return "ignore";
+  if (key === "u") return "undo_archive";
+  return "ignore";
+}
+
 export function resolveIssueDetailGoKeyAction({
   armed,
   defaultPrevented,

ui/src/lib/queryKeys.ts

@@ -95,6 +95,11 @@ export const queryKeys = {
   auth: {
     session: ["auth", "session"] as const,
   },
+  sidebarPreferences: {
+    companyOrder: (userId: string) => ["sidebar-preferences", "company-order", userId] as const,
+    projectOrder: (companyId: string, userId: string) =>
+      ["sidebar-preferences", "project-order", companyId, userId] as const,
+  },
   instance: {
     generalSettings: ["instance", "general-settings"] as const,
     schedulerHeartbeats: ["instance", "scheduler-heartbeats"] as const,

ui/src/pages/CompanyImport.tsx

@@ -13,9 +13,9 @@ import { useToast } from "../context/ToastContext";
 import { authApi } from "../api/auth";
 import { companiesApi } from "../api/companies";
 import { agentsApi } from "../api/agents";
+import { sidebarPreferencesApi } from "../api/sidebarPreferences";
 import { queryKeys } from "../lib/queryKeys";
 import { getAgentOrderStorageKey, writeAgentOrder } from "../lib/agent-order";
-import { getProjectOrderStorageKey, writeProjectOrder } from "../lib/project-order";
 import { MarkdownBody } from "../components/MarkdownBody";
 import { Button } from "@/components/ui/button";
 import { EmptyState } from "../components/EmptyState";
@@ -346,7 +346,7 @@ function prefixedName(prefix: string | null, originalName: string): string {
   return `${prefix}-${originalName}`;
 }
 
-function applyImportedSidebarOrder(
+async function applyImportedSidebarOrder(
   preview: CompanyPortabilityPreviewResult | null,
   result: {
     company: { id: string };
@@ -381,7 +381,7 @@ function applyImportedSidebarOrder(
     writeAgentOrder(getAgentOrderStorageKey(result.company.id, userId), orderedAgentIds);
   }
   if (orderedProjectIds.length > 0) {
-    writeProjectOrder(getProjectOrderStorageKey(result.company.id, userId), orderedProjectIds);
+    await sidebarPreferencesApi.updateProjectOrder(result.company.id, { orderedIds: orderedProjectIds });
   }
 }
 
@@ -859,7 +859,7 @@ export function CompanyImport() {
         ?? refreshedSession?.user?.id
         ?? refreshedSession?.session?.userId
         ?? null;
-      applyImportedSidebarOrder(importPreview, result, sidebarOrderUserId);
+      await applyImportedSidebarOrder(importPreview, result, sidebarOrderUserId);
       setSelectedCompanyId(importedCompany.id);
       pushToast({
         tone: "success",

ui/src/pages/ExecutionWorkspaceDetail.tsx

@@ -15,6 +15,11 @@ import { issuesApi } from "../api/issues";
 import { projectsApi } from "../api/projects";
 import { IssuesList } from "../components/IssuesList";
 import { PageTabBar } from "../components/PageTabBar";
+import {
+  buildWorkspaceRuntimeControlSections,
+  WorkspaceRuntimeControls,
+  type WorkspaceRuntimeControlRequest,
+} from "../components/WorkspaceRuntimeControls";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
@@ -34,7 +39,7 @@ type WorkspaceFormState = {
   workspaceRuntime: string;
 };
 
-type ExecutionWorkspaceTab = "configuration" | "issues";
+type ExecutionWorkspaceTab = "configuration" | "runtime_logs" | "issues";
 
 function resolveExecutionWorkspaceTab(pathname: string, workspaceId: string): ExecutionWorkspaceTab | null {
   const segments = pathname.split("/").filter(Boolean);
@@ -42,10 +47,16 @@ function resolveExecutionWorkspaceTab(pathname: string, workspaceId: string): Ex
   if (executionWorkspacesIndex === -1 || segments[executionWorkspacesIndex + 1] !== workspaceId) return null;
   const tab = segments[executionWorkspacesIndex + 2];
   if (tab === "issues") return "issues";
+  if (tab === "runtime-logs") return "runtime_logs";
   if (tab === "configuration") return "configuration";
   return null;
 }
 
+function executionWorkspaceTabPath(workspaceId: string, tab: ExecutionWorkspaceTab) {
+  const segment = tab === "runtime_logs" ? "runtime-logs" : tab;
+  return `/execution-workspaces/${workspaceId}/${segment}`;
+}
+
 function isSafeExternalUrl(value: string | null | undefined) {
   if (!value) return false;
   try {
@@ -60,10 +71,6 @@ function readText(value: string | null | undefined) {
   return value ?? "";
 }
 
-function hasActiveRuntimeServices(workspace: ExecutionWorkspace | null | undefined) {
-  return (workspace?.runtimeServices ?? []).some((service) => service.status === "starting" || service.status === "running");
-}
-
 function formatJson(value: Record<string, unknown> | null | undefined) {
   if (!value || Object.keys(value).length === 0) return "";
   return JSON.stringify(value, null, 2);
@@ -83,7 +90,7 @@ function parseWorkspaceRuntimeJson(value: string) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {
         ok: false as const,
-        error: "Workspace runtime JSON must be a JSON object.",
+        error: "Workspace commands JSON must be a JSON object.",
       };
     }
     return { ok: true as const, value: parsed as Record<string, unknown> };
@@ -294,7 +301,7 @@ function ExecutionWorkspaceIssuesList({
       projects={projectOptions}
       liveIssueIds={liveIssueIds}
       projectId={project?.id}
-      viewStateKey={`paperclip:execution-workspace-view:${workspaceId}`}
+      viewStateKey="paperclip:execution-workspace-issues-view"
       onUpdateIssue={(id, data) => updateIssue.mutate({ id, data })}
     />
   );
@@ -310,6 +317,7 @@ export function ExecutionWorkspaceDetail() {
   const [form, setForm] = useState<WorkspaceFormState | null>(null);
   const [closeDialogOpen, setCloseDialogOpen] = useState(false);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [runtimeActionErrorMessage, setRuntimeActionErrorMessage] = useState<string | null>(null);
   const [runtimeActionMessage, setRuntimeActionMessage] = useState<string | null>(null);
   const activeTab = workspaceId ? resolveExecutionWorkspaceTab(location.pathname, workspaceId) : null;
 
@@ -377,6 +385,7 @@ export function ExecutionWorkspaceDetail() {
     if (!workspace) return;
     setForm(formStateFromWorkspace(workspace));
     setErrorMessage(null);
+    setRuntimeActionErrorMessage(null);
   }, [workspace]);
 
   useEffect(() => {
@@ -415,24 +424,26 @@ export function ExecutionWorkspaceDetail() {
     enabled: Boolean(workspaceId),
   });
   const controlRuntimeServices = useMutation({
-    mutationFn: (action: "start" | "stop" | "restart") =>
-      executionWorkspacesApi.controlRuntimeServices(workspace!.id, action),
-    onSuccess: (result, action) => {
+    mutationFn: (request: WorkspaceRuntimeControlRequest) =>
+      executionWorkspacesApi.controlRuntimeCommands(workspace!.id, request.action, request),
+    onSuccess: (result, request) => {
       queryClient.setQueryData(queryKeys.executionWorkspaces.detail(result.workspace.id), result.workspace);
       queryClient.invalidateQueries({ queryKey: queryKeys.executionWorkspaces.workspaceOperations(result.workspace.id) });
       queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(result.workspace.projectId) });
-      setErrorMessage(null);
+      setRuntimeActionErrorMessage(null);
       setRuntimeActionMessage(
-        action === "stop"
-          ? "Runtime services stopped."
-          : action === "restart"
-            ? "Runtime services restarted."
-            : "Runtime services started.",
+        request.action === "run"
+          ? "Workspace job completed."
+          : request.action === "stop"
+            ? "Workspace service stopped."
+            : request.action === "restart"
+              ? "Workspace service restarted."
+              : "Workspace service started.",
       );
     },
     onError: (error) => {
       setRuntimeActionMessage(null);
-      setErrorMessage(error instanceof Error ? error.message : "Failed to control runtime services.");
+      setRuntimeActionErrorMessage(error instanceof Error ? error.message : "Failed to control workspace commands.");
     },
   });
 
@@ -446,22 +457,32 @@ export function ExecutionWorkspaceDetail() {
   }
   if (!workspace || !form || !initialState) return null;
 
+  const canRunWorkspaceCommands = Boolean(workspace.cwd);
+  const canStartRuntimeServices = Boolean(effectiveRuntimeConfig) && canRunWorkspaceCommands;
+  const runtimeControlSections = buildWorkspaceRuntimeControlSections({
+    runtimeConfig: effectiveRuntimeConfig,
+    runtimeServices: workspace.runtimeServices ?? [],
+    canStartServices: canStartRuntimeServices,
+    canRunJobs: canRunWorkspaceCommands,
+  });
+  const pendingRuntimeAction = controlRuntimeServices.isPending ? controlRuntimeServices.variables ?? null : null;
+
   if (workspaceId && activeTab === null) {
     let cachedTab: ExecutionWorkspaceTab = "configuration";
     try {
       const storedTab = localStorage.getItem(`paperclip:execution-workspace-tab:${workspaceId}`);
-      if (storedTab === "issues" || storedTab === "configuration") {
+      if (storedTab === "issues" || storedTab === "configuration" || storedTab === "runtime_logs") {
         cachedTab = storedTab;
       }
     } catch {}
-    return <Navigate to={`/execution-workspaces/${workspaceId}/${cachedTab}`} replace />;
+    return <Navigate to={executionWorkspaceTabPath(workspaceId, cachedTab)} replace />;
   }
 
   const handleTabChange = (tab: ExecutionWorkspaceTab) => {
     try {
       localStorage.setItem(`paperclip:execution-workspace-tab:${workspace.id}`, tab);
     } catch {}
-    navigate(`/execution-workspaces/${workspace.id}/${tab}`);
+    navigate(executionWorkspaceTabPath(workspace.id, tab));
   };
 
   const saveChanges = () => {
@@ -485,7 +506,7 @@ export function ExecutionWorkspaceDetail() {
 
   return (
     <>
-      <div className="mx-auto max-w-5xl space-y-4 overflow-hidden sm:space-y-6">
+      <div className="space-y-4 overflow-hidden sm:space-y-6">
         <div className="flex flex-wrap items-center gap-3">
           <Button variant="ghost" size="sm" asChild>
             <Link to={project ? `/projects/${projectRef}/workspaces` : "/projects"}>
@@ -511,10 +532,47 @@ export function ExecutionWorkspaceDetail() {
           </p>
         </div>
 
+        <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+          <div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+            <div className="space-y-1">
+              <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Workspace commands</div>
+              <h2 className="text-lg font-semibold">Services and jobs</h2>
+              <p className="text-sm text-muted-foreground">
+                Source: {runtimeConfigSource === "execution_workspace"
+                  ? "execution workspace override"
+                  : runtimeConfigSource === "project_workspace"
+                    ? "project workspace default"
+                    : "none"}
+              </p>
+            </div>
+          </div>
+          <WorkspaceRuntimeControls
+            className="mt-4"
+            sections={runtimeControlSections}
+            isPending={controlRuntimeServices.isPending}
+            pendingRequest={pendingRuntimeAction}
+            serviceEmptyMessage={
+              effectiveRuntimeConfig
+                ? "No services have been started for this execution workspace yet."
+                : "No workspace command config is defined for this execution workspace yet."
+            }
+            jobEmptyMessage="No one-shot jobs are configured for this execution workspace yet."
+            disabledHint={
+              canStartRuntimeServices
+                ? null
+                : "Execution workspaces need a working directory before local commands can run, and services also need runtime config."
+            }
+            onAction={(request) => controlRuntimeServices.mutate(request)}
+          />
+          {runtimeActionErrorMessage ? <p className="mt-4 text-sm text-destructive">{runtimeActionErrorMessage}</p> : null}
+          {!runtimeActionErrorMessage && runtimeActionMessage ? <p className="mt-4 text-sm text-muted-foreground">{runtimeActionMessage}</p> : null}
+        </div>
+
         <Tabs value={activeTab ?? "configuration"} onValueChange={(value) => handleTabChange(value as ExecutionWorkspaceTab)}>
           <PageTabBar
             items={[
               { value: "configuration", label: "Configuration" },
+              { value: "runtime_logs", label: "Runtime logs" },
               { value: "issues", label: "Issues" },
             ]}
             align="start"
@@ -524,412 +582,333 @@ export function ExecutionWorkspaceDetail() {
         </Tabs>
 
         {activeTab === "configuration" ? (
-          <div className="grid gap-4 sm:gap-6 lg:grid-cols-[minmax(0,1.4fr)_minmax(18rem,0.95fr)]">
-            <div className="min-w-0 space-y-4 sm:space-y-6">
-              <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
-                <div className="flex flex-col gap-4 sm:flex-row sm:flex-wrap sm:items-start sm:justify-between">
-                  <div className="space-y-1">
-                    <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">
-                      Configuration
-                    </div>
-                    <h2 className="text-lg font-semibold">Workspace settings</h2>
-                    <p className="text-sm text-muted-foreground">
-                      Edit the concrete path, repo, branch, provisioning, teardown, and runtime overrides attached to this execution workspace.
-                    </p>
-                  </div>
-                  <Button
-                    variant="outline"
-                    className="w-full sm:w-auto"
-                    onClick={() => setCloseDialogOpen(true)}
-                    disabled={workspace.status === "archived"}
-                  >
-                    {workspace.status === "cleanup_failed" ? "Retry close" : "Close workspace"}
-                  </Button>
-                </div>
-
-                <Separator className="my-5" />
-
-                <div className="grid gap-4 md:grid-cols-2">
-                  <Field label="Workspace name">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none"
-                      value={form.name}
-                      onChange={(event) => setForm((current) => current ? { ...current, name: event.target.value } : current)}
-                      placeholder="Execution workspace name"
-                    />
-                  </Field>
-                  <Field label="Branch name" hint="Useful for isolated worktrees">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
-                      value={form.branchName}
-                      onChange={(event) => setForm((current) => current ? { ...current, branchName: event.target.value } : current)}
-                      placeholder="PAP-946-workspace"
-                    />
-                  </Field>
-                </div>
-
-                <div className="mt-4 grid gap-4 md:grid-cols-2">
-                  <Field label="Working directory">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
-                      value={form.cwd}
-                      onChange={(event) => setForm((current) => current ? { ...current, cwd: event.target.value } : current)}
-                      placeholder="/absolute/path/to/workspace"
-                    />
-                  </Field>
-                  <Field label="Provider path / ref">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
-                      value={form.providerRef}
-                      onChange={(event) => setForm((current) => current ? { ...current, providerRef: event.target.value } : current)}
-                      placeholder="/path/to/worktree or provider ref"
-                    />
-                  </Field>
-                </div>
-
-                <div className="mt-4 grid gap-4 md:grid-cols-2">
-                  <Field label="Repo URL">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none"
-                      value={form.repoUrl}
-                      onChange={(event) => setForm((current) => current ? { ...current, repoUrl: event.target.value } : current)}
-                      placeholder="https://github.com/org/repo"
-                    />
-                  </Field>
-                  <Field label="Base ref">
-                    <input
-                      className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
-                      value={form.baseRef}
-                      onChange={(event) => setForm((current) => current ? { ...current, baseRef: event.target.value } : current)}
-                      placeholder="origin/main"
-                    />
-                  </Field>
-                </div>
-
-                <div className="mt-4 grid gap-4 md:grid-cols-2">
-                  <Field label="Provision command" hint="Runs when Paperclip prepares this execution workspace">
-                    <textarea
-                      className="min-h-20 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-28"
-                      value={form.provisionCommand}
-                      onChange={(event) => setForm((current) => current ? { ...current, provisionCommand: event.target.value } : current)}
-                      placeholder="bash ./scripts/provision-worktree.sh"
-                    />
-                  </Field>
-                  <Field label="Teardown command" hint="Runs when the execution workspace is archived or cleaned up">
-                    <textarea
-                      className="min-h-20 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-28"
-                      value={form.teardownCommand}
-                      onChange={(event) => setForm((current) => current ? { ...current, teardownCommand: event.target.value } : current)}
-                      placeholder="bash ./scripts/teardown-worktree.sh"
-                    />
-                  </Field>
-                </div>
-
-                <div className="mt-4 grid gap-4">
-                  <Field label="Cleanup command" hint="Workspace-specific cleanup before teardown">
-                    <textarea
-                      className="min-h-16 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-24"
-                      value={form.cleanupCommand}
-                      onChange={(event) => setForm((current) => current ? { ...current, cleanupCommand: event.target.value } : current)}
-                      placeholder="pkill -f vite || true"
-                    />
-                  </Field>
-
-                  <div className="rounded-xl border border-dashed border-border/70 bg-muted/20 px-3 py-3">
-                    <div className="flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between">
-                      <div>
-                        <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">
-                          Runtime config source
-                        </div>
-                        <p className="mt-1 text-sm text-muted-foreground">
-                          {runtimeConfigSource === "execution_workspace"
-                            ? "This execution workspace currently overrides the project workspace runtime config."
-                            : runtimeConfigSource === "project_workspace"
-                              ? "This execution workspace is inheriting the project workspace runtime config."
-                              : "No runtime config is currently defined on this execution workspace or its project workspace."}
-                        </p>
-                      </div>
-                      <Button
-                        variant="outline"
-                        className="w-full sm:w-auto"
-                        size="sm"
-                        disabled={!linkedProjectWorkspace?.runtimeConfig?.workspaceRuntime}
-                        onClick={() =>
-                          setForm((current) => current ? {
-                            ...current,
-                            inheritRuntime: true,
-                            workspaceRuntime: "",
-                          } : current)
-                        }
-                      >
-                        Reset to inherit
-                      </Button>
-                    </div>
-                  </div>
-
-                  <Field label="Runtime services JSON" hint="Concrete workspace runtime settings for this execution workspace. Leave this inheriting unless you need a one-off override. If you are missing the right commands, ask your CEO to set them up for you.">
-                    <div className="mb-2 flex items-center gap-2 text-xs text-muted-foreground">
-                      <input
-                        id="inherit-runtime-config"
-                        type="checkbox"
-                        checked={form.inheritRuntime}
-                        onChange={(event) => {
-                          const checked = event.target.checked;
-                          setForm((current) => {
-                            if (!current) return current;
-                            if (!checked && !current.workspaceRuntime.trim() && inheritedRuntimeConfig) {
-                              return { ...current, inheritRuntime: checked, workspaceRuntime: formatJson(inheritedRuntimeConfig) };
-                            }
-                            return { ...current, inheritRuntime: checked };
-                          });
-                        }}
-                      />
-                      <label htmlFor="inherit-runtime-config">Inherit project workspace runtime config</label>
-                    </div>
-                    <textarea
-                      className="min-h-32 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none disabled:cursor-not-allowed disabled:opacity-60 sm:min-h-48"
-                      value={form.workspaceRuntime}
-                      onChange={(event) => setForm((current) => current ? { ...current, workspaceRuntime: event.target.value } : current)}
-                      disabled={form.inheritRuntime}
-                      placeholder={'{\n  "services": [\n    {\n      "name": "web",\n      "command": "pnpm dev",\n      "port": 3100\n    }\n  ]\n}'}
-                    />
-                  </Field>
-                </div>
-
-                <div className="mt-5 flex flex-col items-stretch gap-3 sm:flex-row sm:flex-wrap sm:items-center">
-                  <Button className="w-full sm:w-auto" disabled={!isDirty || updateWorkspace.isPending} onClick={saveChanges}>
-                    {updateWorkspace.isPending ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
-                    Save changes
-                  </Button>
-                  <Button
-                    variant="outline"
-                    className="w-full sm:w-auto"
-                    disabled={!isDirty || updateWorkspace.isPending}
-                    onClick={() => {
-                      setForm(initialState);
-                      setErrorMessage(null);
-                      setRuntimeActionMessage(null);
-                    }}
-                  >
-                    Reset
-                  </Button>
-                  {errorMessage ? <p className="text-sm text-destructive">{errorMessage}</p> : null}
-                  {!errorMessage && runtimeActionMessage ? <p className="text-sm text-muted-foreground">{runtimeActionMessage}</p> : null}
-                  {!errorMessage && !isDirty ? <p className="text-sm text-muted-foreground">No unsaved changes.</p> : null}
-                </div>
-              </div>
-            </div>
-
-            <div className="min-w-0 space-y-4 sm:space-y-6">
-              <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+          <div className="space-y-4 sm:space-y-6">
+            <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+              <div className="flex flex-col gap-4 sm:flex-row sm:flex-wrap sm:items-start sm:justify-between">
                 <div className="space-y-1">
-                  <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Linked objects</div>
-                  <h2 className="text-lg font-semibold">Workspace context</h2>
-                </div>
-                <Separator className="my-4" />
-                <DetailRow label="Project">
-                  {project ? <Link to={`/projects/${projectRef}`} className="hover:underline">{project.name}</Link> : <MonoValue value={workspace.projectId} />}
-                </DetailRow>
-                <DetailRow label="Project workspace">
-                  {project && linkedProjectWorkspace ? (
-                    <WorkspaceLink project={project} workspace={linkedProjectWorkspace} />
-                  ) : workspace.projectWorkspaceId ? (
-                    <MonoValue value={workspace.projectWorkspaceId} />
-                  ) : (
-                    "None"
-                  )}
-                </DetailRow>
-                <DetailRow label="Source issue">
-                  {sourceIssue ? (
-                    <Link to={issueUrl(sourceIssue)} className="hover:underline">
-                      {sourceIssue.identifier ?? sourceIssue.id} · {sourceIssue.title}
-                    </Link>
-                  ) : workspace.sourceIssueId ? (
-                    <MonoValue value={workspace.sourceIssueId} />
-                  ) : (
-                    "None"
-                  )}
-                </DetailRow>
-                <DetailRow label="Derived from">
-                  {derivedWorkspace ? (
-                    <Link to={`/execution-workspaces/${derivedWorkspace.id}/configuration`} className="hover:underline">
-                      {derivedWorkspace.name}
-                    </Link>
-                  ) : workspace.derivedFromExecutionWorkspaceId ? (
-                    <MonoValue value={workspace.derivedFromExecutionWorkspaceId} />
-                  ) : (
-                    "None"
-                  )}
-                </DetailRow>
-                <DetailRow label="Workspace ID">
-                  <MonoValue value={workspace.id} />
-                </DetailRow>
-              </div>
-
-              <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
-                <div className="space-y-1">
-                  <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Paths and refs</div>
-                  <h2 className="text-lg font-semibold">Concrete location</h2>
-                </div>
-                <Separator className="my-4" />
-                <DetailRow label="Working dir">
-                  {workspace.cwd ? <MonoValue value={workspace.cwd} copy /> : "None"}
-                </DetailRow>
-                <DetailRow label="Provider ref">
-                  {workspace.providerRef ? <MonoValue value={workspace.providerRef} copy /> : "None"}
-                </DetailRow>
-                <DetailRow label="Repo URL">
-                  {workspace.repoUrl && isSafeExternalUrl(workspace.repoUrl) ? (
-                    <div className="inline-flex max-w-full items-start gap-2">
-                      <a href={workspace.repoUrl} target="_blank" rel="noreferrer" className="inline-flex min-w-0 items-center gap-1 break-all hover:underline">
-                        {workspace.repoUrl}
-                        <ExternalLink className="h-3.5 w-3.5 shrink-0" />
-                      </a>
-                      <CopyText text={workspace.repoUrl} className="shrink-0 text-muted-foreground hover:text-foreground" copiedLabel="Copied">
-                        <Copy className="h-3.5 w-3.5" />
-                      </CopyText>
-                    </div>
-                  ) : workspace.repoUrl ? (
-                    <MonoValue value={workspace.repoUrl} copy />
-                  ) : (
-                    "None"
-                  )}
-                </DetailRow>
-                <DetailRow label="Base ref">
-                  {workspace.baseRef ? <MonoValue value={workspace.baseRef} copy /> : "None"}
-                </DetailRow>
-                <DetailRow label="Branch">
-                  {workspace.branchName ? <MonoValue value={workspace.branchName} copy /> : "None"}
-                </DetailRow>
-                <DetailRow label="Opened">{formatDateTime(workspace.openedAt)}</DetailRow>
-                <DetailRow label="Last used">{formatDateTime(workspace.lastUsedAt)}</DetailRow>
-                <DetailRow label="Cleanup">
-                  {workspace.cleanupEligibleAt
-                    ? `${formatDateTime(workspace.cleanupEligibleAt)}${workspace.cleanupReason ? ` · ${workspace.cleanupReason}` : ""}`
-                    : "Not scheduled"}
-                </DetailRow>
-              </div>
-
-              <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
-                <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-                  <div className="space-y-1">
-                    <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Runtime services</div>
-                    <h2 className="text-lg font-semibold">Attached services</h2>
-                    <p className="text-sm text-muted-foreground">
-                      Source: {runtimeConfigSource === "execution_workspace"
-                        ? "execution workspace override"
-                        : runtimeConfigSource === "project_workspace"
-                          ? "project workspace default"
-                          : "none"}
-                    </p>
+                  <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">
+                    Configuration
                   </div>
-                  <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:flex-wrap">
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      className="w-full sm:w-auto"
-                      disabled={controlRuntimeServices.isPending || !effectiveRuntimeConfig || !workspace.cwd}
-                      onClick={() => controlRuntimeServices.mutate("start")}
-                    >
-                      {controlRuntimeServices.isPending ? <Loader2 className="mr-2 h-3.5 w-3.5 animate-spin" /> : null}
-                      Start
-                    </Button>
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      className="w-full sm:w-auto"
-                      disabled={controlRuntimeServices.isPending || !effectiveRuntimeConfig || !workspace.cwd}
-                      onClick={() => controlRuntimeServices.mutate("restart")}
-                    >
-                      Restart
-                    </Button>
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      className="w-full sm:w-auto"
-                      disabled={controlRuntimeServices.isPending || !hasActiveRuntimeServices(workspace)}
-                      onClick={() => controlRuntimeServices.mutate("stop")}
-                    >
-                      Stop
-                    </Button>
-                  </div>
-                </div>
-                <Separator className="my-4" />
-                {workspace.runtimeServices && workspace.runtimeServices.length > 0 ? (
-                  <div className="space-y-3">
-                    {workspace.runtimeServices.map((service) => (
-                      <div key={service.id} className="rounded-xl border border-border/80 bg-background px-3 py-2">
-                        <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-                          <div className="space-y-1">
-                            <div className="text-sm font-medium">{service.serviceName}</div>
-                            <div className="text-xs text-muted-foreground">{service.status} · {service.lifecycle}</div>
-                            <div className="space-y-1 text-xs text-muted-foreground">
-                              {service.url ? (
-                                <a href={service.url} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 hover:underline">
-                                  {service.url}
-                                  <ExternalLink className="h-3.5 w-3.5" />
-                                </a>
-                              ) : null}
-                              {service.port ? <div>Port {service.port}</div> : null}
-                              {service.command ? <MonoValue value={service.command} copy /> : null}
-                              {service.cwd ? <MonoValue value={service.cwd} copy /> : null}
-                            </div>
-                          </div>
-                          <StatusPill className="self-start">{service.healthStatus}</StatusPill>
-                        </div>
-                      </div>
-                    ))}
-                  </div>
-                ) : (
+                  <h2 className="text-lg font-semibold">Workspace settings</h2>
                   <p className="text-sm text-muted-foreground">
-                    {effectiveRuntimeConfig
-                      ? "No runtime services are currently running for this execution workspace."
-                      : "No runtime config is defined for this execution workspace yet."}
+                    Edit the concrete path, repo, branch, provisioning, teardown, and runtime overrides attached to this execution workspace.
                   </p>
-                )}
+                </div>
+                <Button
+                  variant="outline"
+                  className="w-full sm:w-auto"
+                  onClick={() => setCloseDialogOpen(true)}
+                  disabled={workspace.status === "archived"}
+                >
+                  {workspace.status === "cleanup_failed" ? "Retry close" : "Close workspace"}
+                </Button>
               </div>
 
-              <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
-                <div className="space-y-1">
-                  <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Recent operations</div>
-                  <h2 className="text-lg font-semibold">Runtime and cleanup logs</h2>
-                </div>
-                <Separator className="my-4" />
-                {workspaceOperationsQuery.isLoading ? (
-                  <p className="text-sm text-muted-foreground">Loading workspace operations…</p>
-                ) : workspaceOperationsQuery.error ? (
-                  <p className="text-sm text-destructive">
-                    {workspaceOperationsQuery.error instanceof Error
-                      ? workspaceOperationsQuery.error.message
-                      : "Failed to load workspace operations."}
-                  </p>
-                ) : workspaceOperationsQuery.data && workspaceOperationsQuery.data.length > 0 ? (
-                  <div className="space-y-3">
-                    {workspaceOperationsQuery.data.slice(0, 6).map((operation) => (
-                      <div key={operation.id} className="rounded-xl border border-border/80 bg-background px-3 py-2">
-                        <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-                          <div className="space-y-1">
-                            <div className="text-sm font-medium">{operation.command ?? operation.phase}</div>
-                            <div className="text-xs text-muted-foreground">
-                              {formatDateTime(operation.startedAt)}
-                              {operation.finishedAt ? ` → ${formatDateTime(operation.finishedAt)}` : ""}
-                            </div>
-                            {operation.stderrExcerpt ? (
-                              <div className="whitespace-pre-wrap break-words text-xs text-destructive">{operation.stderrExcerpt}</div>
-                            ) : operation.stdoutExcerpt ? (
-                              <div className="whitespace-pre-wrap break-words text-xs text-muted-foreground">{operation.stdoutExcerpt}</div>
-                            ) : null}
-                          </div>
-                          <StatusPill className="self-start">{operation.status}</StatusPill>
-                        </div>
+              <Separator className="my-5" />
+
+              <div className="space-y-4">
+                <Field label="Workspace name">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none"
+                    value={form.name}
+                    onChange={(event) => setForm((current) => current ? { ...current, name: event.target.value } : current)}
+                    placeholder="Execution workspace name"
+                  />
+                </Field>
+
+                <Field label="Branch name" hint="Useful for isolated worktrees">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
+                    value={form.branchName}
+                    onChange={(event) => setForm((current) => current ? { ...current, branchName: event.target.value } : current)}
+                    placeholder="PAP-946-workspace"
+                  />
+                </Field>
+
+                <Field label="Working directory">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
+                    value={form.cwd}
+                    onChange={(event) => setForm((current) => current ? { ...current, cwd: event.target.value } : current)}
+                    placeholder="/absolute/path/to/workspace"
+                  />
+                </Field>
+
+                <Field label="Provider path / ref">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
+                    value={form.providerRef}
+                    onChange={(event) => setForm((current) => current ? { ...current, providerRef: event.target.value } : current)}
+                    placeholder="/path/to/worktree or provider ref"
+                  />
+                </Field>
+
+                <Field label="Repo URL">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none"
+                    value={form.repoUrl}
+                    onChange={(event) => setForm((current) => current ? { ...current, repoUrl: event.target.value } : current)}
+                    placeholder="https://github.com/org/repo"
+                  />
+                </Field>
+
+                <Field label="Base ref">
+                  <input
+                    className="w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
+                    value={form.baseRef}
+                    onChange={(event) => setForm((current) => current ? { ...current, baseRef: event.target.value } : current)}
+                    placeholder="origin/main"
+                  />
+                </Field>
+
+                <Field label="Provision command" hint="Runs when Paperclip prepares this execution workspace">
+                  <textarea
+                    className="min-h-20 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-28"
+                    value={form.provisionCommand}
+                    onChange={(event) => setForm((current) => current ? { ...current, provisionCommand: event.target.value } : current)}
+                    placeholder="bash ./scripts/provision-worktree.sh"
+                  />
+                </Field>
+
+                <Field label="Teardown command" hint="Runs when the execution workspace is archived or cleaned up">
+                  <textarea
+                    className="min-h-20 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-28"
+                    value={form.teardownCommand}
+                    onChange={(event) => setForm((current) => current ? { ...current, teardownCommand: event.target.value } : current)}
+                    placeholder="bash ./scripts/teardown-worktree.sh"
+                  />
+                </Field>
+
+                <Field label="Cleanup command" hint="Workspace-specific cleanup before teardown">
+                  <textarea
+                    className="min-h-16 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none sm:min-h-24"
+                    value={form.cleanupCommand}
+                    onChange={(event) => setForm((current) => current ? { ...current, cleanupCommand: event.target.value } : current)}
+                    placeholder="pkill -f vite || true"
+                  />
+                </Field>
+
+                <div className="rounded-xl border border-dashed border-border/70 bg-muted/20 px-3 py-3">
+                  <div className="flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between">
+                    <div>
+                      <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">
+                        Runtime config source
                       </div>
-                    ))}
+                      <p className="mt-1 text-sm text-muted-foreground">
+                        {runtimeConfigSource === "execution_workspace"
+                          ? "This execution workspace currently overrides the project workspace runtime config."
+                          : runtimeConfigSource === "project_workspace"
+                            ? "This execution workspace is inheriting the project workspace runtime config."
+                            : "No runtime config is currently defined on this execution workspace or its project workspace."}
+                      </p>
+                    </div>
+                    <Button
+                      variant="outline"
+                      className="w-full sm:w-auto"
+                      size="sm"
+                      disabled={!linkedProjectWorkspace?.runtimeConfig?.workspaceRuntime}
+                      onClick={() =>
+                        setForm((current) => current ? {
+                          ...current,
+                          inheritRuntime: true,
+                          workspaceRuntime: "",
+                        } : current)
+                      }
+                    >
+                      Reset to inherit
+                    </Button>
                   </div>
-                ) : (
-                  <p className="text-sm text-muted-foreground">No workspace operations have been recorded yet.</p>
-                )}
+                </div>
+
+                <details className="rounded-xl border border-dashed border-border/70 bg-muted/20 px-3 py-3">
+                  <summary className="cursor-pointer text-sm font-medium">Advanced runtime JSON</summary>
+                  <p className="mt-2 text-sm text-muted-foreground">
+                    Override the inherited workspace command model only when this execution workspace truly needs different service or job behavior.
+                  </p>
+                  <div className="mt-3">
+                    <Field label="Workspace commands JSON" hint="Legacy `services` arrays still work, but `commands` supports both services and jobs.">
+                      <div className="mb-2 flex items-center gap-2 text-xs text-muted-foreground">
+                        <input
+                          id="inherit-runtime-config"
+                          type="checkbox"
+                          checked={form.inheritRuntime}
+                          onChange={(event) => {
+                            const checked = event.target.checked;
+                            setForm((current) => {
+                              if (!current) return current;
+                              if (!checked && !current.workspaceRuntime.trim() && inheritedRuntimeConfig) {
+                                return { ...current, inheritRuntime: checked, workspaceRuntime: formatJson(inheritedRuntimeConfig) };
+                              }
+                              return { ...current, inheritRuntime: checked };
+                            });
+                          }}
+                        />
+                        <label htmlFor="inherit-runtime-config">Inherit project workspace runtime config</label>
+                      </div>
+                      <textarea
+                        className="min-h-64 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none disabled:cursor-not-allowed disabled:opacity-60 sm:min-h-96"
+                        value={form.workspaceRuntime}
+                        onChange={(event) => setForm((current) => current ? { ...current, workspaceRuntime: event.target.value } : current)}
+                        disabled={form.inheritRuntime}
+                        placeholder={'{\n  "commands": [\n    {\n      "id": "web",\n      "name": "web",\n      "kind": "service",\n      "command": "pnpm dev",\n      "cwd": ".",\n      "port": { "type": "auto" }\n    },\n    {\n      "id": "db-migrate",\n      "name": "db:migrate",\n      "kind": "job",\n      "command": "pnpm db:migrate",\n      "cwd": "."\n    }\n  ]\n}'}
+                      />
+                    </Field>
+                  </div>
+                </details>
+              </div>
+
+              <div className="mt-5 flex flex-col items-stretch gap-3 sm:flex-row sm:flex-wrap sm:items-center">
+                <Button className="w-full sm:w-auto" disabled={!isDirty || updateWorkspace.isPending} onClick={saveChanges}>
+                  {updateWorkspace.isPending ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+                  Save changes
+                </Button>
+                <Button
+                  variant="outline"
+                  className="w-full sm:w-auto"
+                  disabled={!isDirty || updateWorkspace.isPending}
+                  onClick={() => {
+                    setForm(initialState);
+                    setErrorMessage(null);
+                    setRuntimeActionErrorMessage(null);
+                    setRuntimeActionMessage(null);
+                  }}
+                >
+                  Reset
+                </Button>
+                {errorMessage ? <p className="text-sm text-destructive">{errorMessage}</p> : null}
+                {!errorMessage && !isDirty ? <p className="text-sm text-muted-foreground">No unsaved changes.</p> : null}
               </div>
             </div>
+
+            <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+              <div className="space-y-1">
+                <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Linked objects</div>
+                <h2 className="text-lg font-semibold">Workspace context</h2>
+              </div>
+              <Separator className="my-4" />
+              <DetailRow label="Project">
+                {project ? <Link to={`/projects/${projectRef}`} className="hover:underline">{project.name}</Link> : <MonoValue value={workspace.projectId} />}
+              </DetailRow>
+              <DetailRow label="Project workspace">
+                {project && linkedProjectWorkspace ? (
+                  <WorkspaceLink project={project} workspace={linkedProjectWorkspace} />
+                ) : workspace.projectWorkspaceId ? (
+                  <MonoValue value={workspace.projectWorkspaceId} />
+                ) : (
+                  "None"
+                )}
+              </DetailRow>
+              <DetailRow label="Source issue">
+                {sourceIssue ? (
+                  <Link to={issueUrl(sourceIssue)} className="hover:underline">
+                    {sourceIssue.identifier ?? sourceIssue.id} · {sourceIssue.title}
+                  </Link>
+                ) : workspace.sourceIssueId ? (
+                  <MonoValue value={workspace.sourceIssueId} />
+                ) : (
+                  "None"
+                )}
+              </DetailRow>
+              <DetailRow label="Derived from">
+                {derivedWorkspace ? (
+                  <Link to={executionWorkspaceTabPath(derivedWorkspace.id, "configuration")} className="hover:underline">
+                    {derivedWorkspace.name}
+                  </Link>
+                ) : workspace.derivedFromExecutionWorkspaceId ? (
+                  <MonoValue value={workspace.derivedFromExecutionWorkspaceId} />
+                ) : (
+                  "None"
+                )}
+              </DetailRow>
+              <DetailRow label="Workspace ID">
+                <MonoValue value={workspace.id} />
+              </DetailRow>
+            </div>
+
+            <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+              <div className="space-y-1">
+                <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Paths and refs</div>
+                <h2 className="text-lg font-semibold">Concrete location</h2>
+              </div>
+              <Separator className="my-4" />
+              <DetailRow label="Working dir">
+                {workspace.cwd ? <MonoValue value={workspace.cwd} copy /> : "None"}
+              </DetailRow>
+              <DetailRow label="Provider ref">
+                {workspace.providerRef ? <MonoValue value={workspace.providerRef} copy /> : "None"}
+              </DetailRow>
+              <DetailRow label="Repo URL">
+                {workspace.repoUrl && isSafeExternalUrl(workspace.repoUrl) ? (
+                  <div className="inline-flex max-w-full items-start gap-2">
+                    <a href={workspace.repoUrl} target="_blank" rel="noreferrer" className="inline-flex min-w-0 items-center gap-1 break-all hover:underline">
+                      {workspace.repoUrl}
+                      <ExternalLink className="h-3.5 w-3.5 shrink-0" />
+                    </a>
+                    <CopyText text={workspace.repoUrl} className="shrink-0 text-muted-foreground hover:text-foreground" copiedLabel="Copied">
+                      <Copy className="h-3.5 w-3.5" />
+                    </CopyText>
+                  </div>
+                ) : workspace.repoUrl ? (
+                  <MonoValue value={workspace.repoUrl} copy />
+                ) : (
+                  "None"
+                )}
+              </DetailRow>
+              <DetailRow label="Base ref">
+                {workspace.baseRef ? <MonoValue value={workspace.baseRef} copy /> : "None"}
+              </DetailRow>
+              <DetailRow label="Branch">
+                {workspace.branchName ? <MonoValue value={workspace.branchName} copy /> : "None"}
+              </DetailRow>
+              <DetailRow label="Opened">{formatDateTime(workspace.openedAt)}</DetailRow>
+              <DetailRow label="Last used">{formatDateTime(workspace.lastUsedAt)}</DetailRow>
+              <DetailRow label="Cleanup">
+                {workspace.cleanupEligibleAt
+                  ? `${formatDateTime(workspace.cleanupEligibleAt)}${workspace.cleanupReason ? ` · ${workspace.cleanupReason}` : ""}`
+                  : "Not scheduled"}
+              </DetailRow>
+            </div>
+          </div>
+        ) : activeTab === "runtime_logs" ? (
+          <div className="rounded-2xl border border-border bg-card p-4 sm:p-5">
+            <div className="space-y-1">
+              <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Recent operations</div>
+              <h2 className="text-lg font-semibold">Runtime and cleanup logs</h2>
+            </div>
+            <Separator className="my-4" />
+            {workspaceOperationsQuery.isLoading ? (
+              <p className="text-sm text-muted-foreground">Loading workspace operations…</p>
+            ) : workspaceOperationsQuery.error ? (
+              <p className="text-sm text-destructive">
+                {workspaceOperationsQuery.error instanceof Error
+                  ? workspaceOperationsQuery.error.message
+                  : "Failed to load workspace operations."}
+              </p>
+            ) : workspaceOperationsQuery.data && workspaceOperationsQuery.data.length > 0 ? (
+              <div className="space-y-3">
+                {workspaceOperationsQuery.data.map((operation) => (
+                  <div key={operation.id} className="rounded-xl border border-border/80 bg-background px-3 py-2">
+                    <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                      <div className="space-y-1">
+                        <div className="text-sm font-medium">{operation.command ?? operation.phase}</div>
+                        <div className="text-xs text-muted-foreground">
+                          {formatDateTime(operation.startedAt)}
+                          {operation.finishedAt ? ` → ${formatDateTime(operation.finishedAt)}` : ""}
+                        </div>
+                        {operation.stderrExcerpt ? (
+                          <div className="whitespace-pre-wrap break-words text-xs text-destructive">{operation.stderrExcerpt}</div>
+                        ) : operation.stdoutExcerpt ? (
+                          <div className="whitespace-pre-wrap break-words text-xs text-muted-foreground">{operation.stdoutExcerpt}</div>
+                        ) : null}
+                      </div>
+                      <StatusPill className="self-start">{operation.status}</StatusPill>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <p className="text-sm text-muted-foreground">No workspace operations have been recorded yet.</p>
+            )}
           </div>
         ) : (
           <ExecutionWorkspaceIssuesList

ui/src/pages/Inbox.test.tsx

@@ -5,7 +5,7 @@ import type { ComponentProps } from "react";
 import { createRoot } from "react-dom/client";
 import type { Issue } from "@paperclipai/shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { FailedRunInboxRow, InboxIssueMetaLeading, InboxIssueTrailingColumns } from "./Inbox";
+import { FailedRunInboxRow, InboxGroupHeader, InboxIssueMetaLeading, InboxIssueTrailingColumns } from "./Inbox";
 
 vi.mock("@/lib/router", () => ({
   Link: ({ children, className, ...props }: ComponentProps<"a">) => (
@@ -245,3 +245,52 @@ describe("InboxIssueTrailingColumns", () => {
     });
   });
 });
+
+describe("InboxGroupHeader", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("shows a left caret and expanded state for collapsible mobile headers", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(<InboxGroupHeader label="Primary workspace (default)" collapsible collapsed={false} />);
+    });
+
+    const button = container.querySelector("button");
+    expect(button).not.toBeNull();
+    expect(button?.getAttribute("aria-expanded")).toBe("true");
+    expect(button?.textContent).toContain("Primary workspace (default)");
+    const caret = container.querySelector("svg");
+    expect(caret?.className.baseVal).toContain("rotate-90");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("keeps the caret collapsed when the mobile group is hidden", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(<InboxGroupHeader label="Feature Branch" collapsible collapsed />);
+    });
+
+    const button = container.querySelector("button");
+    expect(button?.getAttribute("aria-expanded")).toBe("false");
+    const caret = container.querySelector("svg");
+    expect(caret?.className.baseVal).not.toContain("rotate-90");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});

ui/src/pages/Inbox.tsx

@@ -34,10 +34,12 @@ import { prefetchIssueDetail } from "../lib/issueDetailCache";
 import {
   hasBlockingShortcutDialog,
   isKeyboardShortcutTextInputTarget,
+  resolveInboxUndoArchiveKeyAction,
   shouldBlurPageSearchOnEnter,
   shouldBlurPageSearchOnEscape,
 } from "../lib/keyboardShortcuts";
 import { EmptyState } from "../components/EmptyState";
+import { IssueGroupHeader } from "../components/IssueGroupHeader";
 import { PageSkeleton } from "../components/PageSkeleton";
 import {
   InboxIssueMetaLeading,
@@ -93,12 +95,14 @@ import type { Approval, HeartbeatRun, Issue, JoinRequest } from "@paperclipai/sh
 import {
   ACTIONABLE_APPROVAL_STATUSES,
   DEFAULT_INBOX_ISSUE_COLUMNS,
+  buildInboxKeyboardNavEntries,
   buildInboxNesting,
   getAvailableInboxIssueColumns,
+  getInboxWorkItemKey,
   getApprovalsForTab,
   getArchivedInboxSearchIssues,
-  getInboxWorkItems,
   getInboxKeyboardSelectionIndex,
+  getInboxWorkItems,
   getInboxSearchSupplementIssues,
   getLatestFailedRunsByAgent,
   matchesInboxIssueSearch,
@@ -106,22 +110,27 @@ import {
   groupInboxWorkItems,
   isInboxEntityDismissed,
   isMineInboxTab,
+  loadCollapsedInboxGroupKeys,
   loadInboxFilterPreferences,
   loadInboxIssueColumns,
   loadInboxNesting,
   loadInboxWorkItemGroupBy,
   normalizeInboxIssueColumns,
   resolveInboxNestingEnabled,
+  shouldResetInboxWorkspaceGrouping,
   resolveIssueWorkspaceName,
   resolveInboxSelectionIndex,
   saveInboxFilterPreferences,
+  saveCollapsedInboxGroupKeys,
   saveInboxIssueColumns,
   saveInboxNesting,
   saveInboxWorkItemGroupBy,
+  type InboxWorkspaceGroupingOptions,
   type InboxApprovalFilter,
   type InboxCategoryFilter,
   type InboxFilterPreferences,
   type InboxIssueColumn,
+  type InboxKeyboardNavEntry,
   saveLastInboxTab,
   shouldShowInboxSection,
   type InboxTab,
@@ -131,14 +140,13 @@ import {
 import { useDismissedInboxAlerts, useInboxDismissals, useReadInboxItems } from "../hooks/useInboxBadge";
 
 export { InboxIssueMetaLeading, InboxIssueTrailingColumns } from "../components/IssueColumns";
+export { IssueGroupHeader as InboxGroupHeader } from "../components/IssueGroupHeader";
 type SectionKey =
   | "work_items"
   | "alerts";
 
 /** A flat navigation entry for keyboard j/k traversal that includes expanded children. */
-type NavEntry =
-  | { type: "top"; index: number; item: InboxWorkItem }
-  | { type: "child"; parentIndex: number; issue: Issue };
+type NavEntry = InboxKeyboardNavEntry;
 
 type InboxGroupedSection = {
   key: string;
@@ -152,11 +160,12 @@ function buildGroupedInboxSections(
   items: InboxWorkItem[],
   groupBy: InboxWorkItemGroupBy,
   nestingEnabled: boolean,
+  workspaceGrouping: InboxWorkspaceGroupingOptions,
   options?: { keyPrefix?: string; isArchivedSearch?: boolean },
 ): InboxGroupedSection[] {
   const keyPrefix = options?.keyPrefix ?? "";
   const isArchivedSearch = options?.isArchivedSearch ?? false;
-  return groupInboxWorkItems(items, groupBy).map((group) => {
+  return groupInboxWorkItems(items, groupBy, workspaceGrouping).map((group) => {
     const nestedGroup = nestingEnabled && group.items.some((item) => item.kind === "issue")
       ? buildInboxNesting(group.items)
       : { displayItems: group.items, childrenByIssueId: new Map<string, Issue[]>() };
@@ -643,6 +652,7 @@ export function Inbox() {
     queryFn: () => instanceSettingsApi.getExperimental(),
     retry: false,
   });
+  const experimentalSettingsLoaded = experimentalSettings !== undefined;
   const [searchQuery, setSearchQuery] = useState("");
   const normalizedSearchQuery = searchQuery.trim();
   const [filterPreferences, setFilterPreferences] = useState<InboxFilterPreferences>(
@@ -716,6 +726,7 @@ export function Inbox() {
     if (previousSelectedCompanyIdRef.current !== selectedCompanyId) {
       previousSelectedCompanyIdRef.current = selectedCompanyId;
       setFilterPreferences(loadInboxFilterPreferences(selectedCompanyId));
+      setCollapsedGroupKeys(loadCollapsedInboxGroupKeys(selectedCompanyId));
     }
   }, [selectedCompanyId]);
 
@@ -877,6 +888,14 @@ export function Inbox() {
     }
     return map;
   }, [executionWorkspaces]);
+  const inboxWorkspaceGrouping = useMemo<InboxWorkspaceGroupingOptions>(
+    () => ({
+      executionWorkspaceById,
+      projectWorkspaceById,
+      defaultProjectWorkspaceIdByProjectId,
+    }),
+    [defaultProjectWorkspaceIdByProjectId, executionWorkspaceById, projectWorkspaceById],
+  );
   const visibleIssueColumnSet = useMemo(() => new Set(visibleIssueColumns), [visibleIssueColumns]);
   const availableIssueColumns = useMemo(
     () => getAvailableInboxIssueColumns(isolatedWorkspacesEnabled),
@@ -1078,6 +1097,11 @@ export function Inbox() {
   // --- Parent-child nesting for inbox issues ---
   const [nestingPreferenceEnabled, setNestingPreferenceEnabled] = useState(() => loadInboxNesting());
   const nestingEnabled = resolveInboxNestingEnabled(nestingPreferenceEnabled, isMobile);
+  useEffect(() => {
+    if (!shouldResetInboxWorkspaceGrouping(groupBy, isolatedWorkspacesEnabled, experimentalSettingsLoaded)) return;
+    setGroupBy("none");
+    saveInboxWorkItemGroupBy("none");
+  }, [experimentalSettingsLoaded, groupBy, isolatedWorkspacesEnabled]);
   const toggleNesting = useCallback(() => {
     setNestingPreferenceEnabled((prev) => {
       const next = !prev;
@@ -1086,15 +1110,26 @@ export function Inbox() {
     });
   }, []);
   const [collapsedInboxParents, setCollapsedInboxParents] = useState<Set<string>>(new Set());
+  const [collapsedGroupKeys, setCollapsedGroupKeys] = useState<Set<string>>(() => loadCollapsedInboxGroupKeys(selectedCompanyId));
+  const toggleGroupCollapse = useCallback((groupKey: string) => {
+    setCollapsedGroupKeys((prev) => {
+      const next = new Set(prev);
+      if (next.has(groupKey)) next.delete(groupKey);
+      else next.add(groupKey);
+      saveCollapsedInboxGroupKeys(selectedCompanyId, next);
+      return next;
+    });
+  }, [selectedCompanyId]);
   const groupedSections = useMemo<InboxGroupedSection[]>(() => [
-    ...buildGroupedInboxSections(effectiveWorkItems, groupBy, nestingEnabled),
+    ...buildGroupedInboxSections(effectiveWorkItems, groupBy, nestingEnabled, inboxWorkspaceGrouping),
     ...buildGroupedInboxSections(
       getInboxWorkItems({ issues: archivedSearchIssues, approvals: [] }),
       groupBy,
       nestingEnabled,
+      inboxWorkspaceGrouping,
       { keyPrefix: "archived-search:", isArchivedSearch: true },
     ),
-  ], [archivedSearchIssues, effectiveWorkItems, groupBy, nestingEnabled]);
+  ], [archivedSearchIssues, effectiveWorkItems, groupBy, inboxWorkspaceGrouping, nestingEnabled]);
   const totalVisibleWorkItems = useMemo(
     () => groupedSections.reduce((count, group) => count + group.displayItems.length, 0),
     [groupedSections],
@@ -1108,27 +1143,24 @@ export function Inbox() {
     });
   }, []);
 
-  // Build flat navigation list including expanded children for keyboard traversal
+  // Build flat navigation list from visible rows so keyboard traversal respects collapsed groups.
   const flatNavItems = useMemo((): NavEntry[] => {
-    const entries: NavEntry[] = [];
-    let topIndex = 0;
-    for (const group of groupedSections) {
-      for (const item of group.displayItems) {
-        entries.push({ type: "top", index: topIndex, item });
-        if (item.kind === "issue") {
-          const children = group.childrenByIssueId.get(item.issue.id);
-          const isExpanded = children?.length && !collapsedInboxParents.has(item.issue.id);
-          if (isExpanded) {
-            for (const child of children) {
-              entries.push({ type: "child", parentIndex: topIndex, issue: child });
-            }
-          }
-        }
-        topIndex += 1;
-      }
-    }
-    return entries;
-  }, [groupedSections, collapsedInboxParents]);
+    return buildInboxKeyboardNavEntries(groupedSections, collapsedGroupKeys, collapsedInboxParents);
+  }, [collapsedGroupKeys, collapsedInboxParents, groupedSections]);
+  const topFlatIndex = useMemo(() => {
+    const map = new Map<string, number>();
+    flatNavItems.forEach((entry, index) => {
+      if (entry.type === "top") map.set(entry.itemKey, index);
+    });
+    return map;
+  }, [flatNavItems]);
+  const childFlatIndex = useMemo(() => {
+    const map = new Map<string, number>();
+    flatNavItems.forEach((entry, index) => {
+      if (entry.type === "child") map.set(entry.issueId, index);
+    });
+    return map;
+  }, [flatNavItems]);
 
   const agentName = (id: string | null) => {
     if (!id) return null;
@@ -1267,6 +1299,8 @@ export function Inbox() {
   const [fadingOutIssues, setFadingOutIssues] = useState<Set<string>>(new Set());
   const [showMarkAllReadConfirm, setShowMarkAllReadConfirm] = useState(false);
   const [archivingIssueIds, setArchivingIssueIds] = useState<Set<string>>(new Set());
+  const [undoableArchiveIssueIds, setUndoableArchiveIssueIds] = useState<string[]>([]);
+  const [unarchivingIssueIds, setUnarchivingIssueIds] = useState<Set<string>>(new Set());
   const [fadingNonIssueItems, setFadingNonIssueItems] = useState<Set<string>>(new Set());
   const [archivingNonIssueIds, setArchivingNonIssueIds] = useState<Set<string>>(new Set());
   const [selectedIndex, setSelectedIndex] = useState<number>(-1);
@@ -1321,7 +1355,7 @@ export function Inbox() {
         }
       }
     },
-    onSettled: (_data, error, id) => {
+    onSettled: (_data, _error, id) => {
       // Clean up archiving state and refetch to sync with server
       setArchivingIssueIds((prev) => {
         const next = new Set(prev);
@@ -1330,6 +1364,34 @@ export function Inbox() {
       });
       invalidateInboxIssueQueries();
     },
+    onSuccess: (_data, id) => {
+      setUndoableArchiveIssueIds((prev) => [...prev.filter((issueId) => issueId !== id), id]);
+    },
+  });
+
+  const unarchiveIssueMutation = useMutation({
+    mutationFn: (id: string) => issuesApi.unarchiveFromInbox(id),
+    onMutate: (id) => {
+      setActionError(null);
+      setUnarchivingIssueIds((prev) => new Set(prev).add(id));
+    },
+    onError: (err) => {
+      setActionError(err instanceof Error ? err.message : "Failed to undo inbox archive");
+    },
+    onSuccess: (_data, id) => {
+      setUndoableArchiveIssueIds((prev) => {
+        const next = prev.filter((issueId) => issueId !== id);
+        return next;
+      });
+    },
+    onSettled: (_data, _error, id) => {
+      setUnarchivingIssueIds((prev) => {
+        const next = new Set(prev);
+        next.delete(id);
+        return next;
+      });
+      invalidateInboxIssueQueries();
+    },
   });
 
   const markReadMutation = useMutation({
@@ -1420,18 +1482,16 @@ export function Inbox() {
     return "hidden";
   };
 
-  const getWorkItemKey = useCallback((item: InboxWorkItem): string => {
-    if (item.kind === "issue") return `issue:${item.issue.id}`;
-    if (item.kind === "approval") return `approval:${item.approval.id}`;
-    if (item.kind === "failed_run") return `run:${item.run.id}`;
-    return `join:${item.joinRequest.id}`;
-  }, []);
-
   // Keep selection valid when the list shape changes, but do not auto-select on initial load.
   useEffect(() => {
     setSelectedIndex((prev) => resolveInboxSelectionIndex(prev, flatNavItems.length));
   }, [flatNavItems.length]);
 
+  useEffect(() => {
+    setUndoableArchiveIssueIds([]);
+    setUnarchivingIssueIds(new Set());
+  }, [selectedCompanyId]);
+
   // Use refs for keyboard handler to avoid stale closures
   const kbStateRef = useRef({
     workItems: groupedSections,
@@ -1440,6 +1500,8 @@ export function Inbox() {
     canArchive: canArchiveFromTab,
     archivedSearchIssueIds,
     archivingIssueIds,
+    undoableArchiveIssueIds,
+    unarchivingIssueIds,
     archivingNonIssueIds,
     fadingOutIssues,
     readItems,
@@ -1451,6 +1513,8 @@ export function Inbox() {
     canArchive: canArchiveFromTab,
     archivedSearchIssueIds,
     archivingIssueIds,
+    undoableArchiveIssueIds,
+    unarchivingIssueIds,
     archivingNonIssueIds,
     fadingOutIssues,
     readItems,
@@ -1458,6 +1522,7 @@ export function Inbox() {
 
   const kbActionsRef = useRef({
     archiveIssue: (id: string) => archiveIssueMutation.mutate(id),
+    undoArchiveIssue: (id: string) => unarchiveIssueMutation.mutate(id),
     archiveNonIssue: handleArchiveNonIssue,
     markRead: (id: string) => markReadMutation.mutate(id),
     markUnreadIssue: (id: string) => markUnreadMutation.mutate(id),
@@ -1467,6 +1532,7 @@ export function Inbox() {
   });
   kbActionsRef.current = {
     archiveIssue: (id: string) => archiveIssueMutation.mutate(id),
+    undoArchiveIssue: (id: string) => unarchiveIssueMutation.mutate(id),
     archiveNonIssue: handleArchiveNonIssue,
     markRead: (id: string) => markReadMutation.mutate(id),
     markUnreadIssue: (id: string) => markUnreadMutation.mutate(id),
@@ -1501,6 +1567,24 @@ export function Inbox() {
       // Keyboard shortcuts are only active on the "mine" tab
       if (!st.canArchive) return;
 
+      const undoArchiveAction = resolveInboxUndoArchiveKeyAction({
+        hasUndoableArchive: st.undoableArchiveIssueIds.length > 0,
+        defaultPrevented: e.defaultPrevented,
+        key: e.key,
+        metaKey: e.metaKey,
+        ctrlKey: e.ctrlKey,
+        altKey: e.altKey,
+        target,
+        hasOpenDialog: hasBlockingShortcutDialog(document),
+      });
+      if (undoArchiveAction === "undo_archive") {
+        const issueId = st.undoableArchiveIssueIds[st.undoableArchiveIssueIds.length - 1];
+        if (!issueId || st.unarchivingIssueIds.has(issueId)) return;
+        e.preventDefault();
+        act.undoArchiveIssue(issueId);
+        return;
+      }
+
       const navItems = st.flatNavItems;
       const navCount = navItems.length;
       if (navCount === 0) return;
@@ -1537,7 +1621,7 @@ export function Inbox() {
                 act.archiveIssue(item.issue.id);
               }
             } else {
-              const key = getWorkItemKey(item);
+              const key = getInboxWorkItemKey(item);
               if (!st.archivingNonIssueIds.has(key)) act.archiveNonIssue(key);
             }
           }
@@ -1551,7 +1635,7 @@ export function Inbox() {
             act.markUnreadIssue(issue.id);
           } else if (item) {
             if (item.kind === "issue") act.markUnreadIssue(item.issue.id);
-            else act.markNonIssueUnread(getWorkItemKey(item));
+            else act.markNonIssueUnread(getInboxWorkItemKey(item));
           }
           break;
         }
@@ -1565,7 +1649,7 @@ export function Inbox() {
             if (item.kind === "issue") {
               if (item.issue.isUnreadForMe && !st.fadingOutIssues.has(item.issue.id)) act.markRead(item.issue.id);
             } else {
-              const key = getWorkItemKey(item);
+              const key = getInboxWorkItemKey(item);
               if (!st.readItems.has(key)) act.markNonIssueRead(key);
             }
           }
@@ -1604,7 +1688,7 @@ export function Inbox() {
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [getWorkItemKey, issueLinkState, keyboardShortcutsEnabled]);
+  }, [issueLinkState, keyboardShortcutsEnabled]);
 
   // Scroll selected item into view
   useEffect(() => {
@@ -1780,6 +1864,7 @@ export function Inbox() {
                 {([
                   ["none", "None"],
                   ["type", "Type"],
+                  ...(isolatedWorkspacesEnabled ? ([["workspace", "Workspace"]] as const) : []),
                 ] as const).map(([value, label]) => (
                   <button
                     key={value}
@@ -1913,27 +1998,6 @@ export function Inbox() {
           <div>
             <div ref={listRef} className="overflow-hidden rounded-xl border border-border bg-card">
               {(() => {
-                // Pre-compute flat nav index for each top-level item and child issue.
-                let flatIdx = 0;
-                const topFlatIndex = new Map<string, number>();
-                const childFlatIndex = new Map<string, number>();
-                for (const group of groupedSections) {
-                  for (const topItem of group.displayItems) {
-                    const itemKey = `${group.key}:${getWorkItemKey(topItem)}`;
-                    topFlatIndex.set(itemKey, flatIdx);
-                    flatIdx++;
-                    if (topItem.kind === "issue") {
-                      const children = group.childrenByIssueId.get(topItem.issue.id);
-                      const isExpanded = children?.length && !collapsedInboxParents.has(topItem.issue.id);
-                      if (isExpanded) {
-                        for (const child of children) {
-                          childFlatIndex.set(child.id, flatIdx);
-                          flatIdx++;
-                        }
-                      }
-                    }
-                  }
-                }
                 const renderInboxIssue = ({
                   issue,
                   depth,
@@ -2046,6 +2110,7 @@ export function Inbox() {
                 let previousTimestamp = Number.POSITIVE_INFINITY;
                 return groupedSections.flatMap((group, groupIndex) => {
                   const elements: ReactNode[] = [];
+                  const isGroupCollapsed = collapsedGroupKeys.has(group.key);
                   if (group.isArchivedSearch && (groupIndex === 0 || !groupedSections[groupIndex - 1]?.isArchivedSearch)) {
                     elements.push(
                       <div
@@ -2065,18 +2130,24 @@ export function Inbox() {
                       <div
                         key={`group-${group.key}`}
                         className={cn(
-                          "border-b border-border/70 bg-muted/30 px-4 py-2 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground",
-                          groupIndex > 0 && "border-t border-border",
+                          "px-3 sm:px-4",
+                          groupIndex > 0 && "pt-2",
                         )}
                       >
-                        {group.label}
+                        <IssueGroupHeader
+                          label={group.label}
+                          collapsible
+                          collapsed={isGroupCollapsed}
+                          onToggle={() => toggleGroupCollapse(group.key)}
+                        />
                       </div>,
                     );
                   }
+                  if (isGroupCollapsed) return elements;
 
                   for (let index = 0; index < group.displayItems.length; index += 1) {
                     const item = group.displayItems[index]!;
-                    const navIdx = topFlatIndex.get(`${group.key}:${getWorkItemKey(item)}`) ?? 0;
+                    const navIdx = topFlatIndex.get(`${group.key}:${getInboxWorkItemKey(item)}`) ?? 0;
                     const wrapItem = (key: string, isSelected: boolean, child: ReactNode) => (
                       <div
                         key={`sel-${key}`}

ui/src/pages/ProjectDetail.tsx

@@ -16,7 +16,6 @@ import { useToast } from "../context/ToastContext";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { queryKeys } from "../lib/queryKeys";
 import { ProjectProperties, type ProjectConfigFieldKey, type ProjectFieldSaveState } from "../components/ProjectProperties";
-import { CopyText } from "../components/CopyText";
 import { InlineEditor } from "../components/InlineEditor";
 import { StatusBadge } from "../components/StatusBadge";
 import { BudgetPolicyCard } from "../components/BudgetPolicyCard";
@@ -24,15 +23,14 @@ import { ExecutionWorkspaceCloseDialog } from "../components/ExecutionWorkspaceC
 import { IssuesList } from "../components/IssuesList";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { PageTabBar } from "../components/PageTabBar";
+import { ProjectWorkspaceSummaryCard } from "../components/ProjectWorkspaceSummaryCard";
 import { buildProjectWorkspaceSummaries } from "../lib/project-workspaces-tab";
-import { projectRouteRef, projectWorkspaceUrl } from "../lib/utils";
-import { timeAgo } from "../lib/timeAgo";
+import { projectRouteRef } from "../lib/utils";
 import { Button } from "@/components/ui/button";
 import { Tabs } from "@/components/ui/tabs";
 import { PluginLauncherOutlet } from "@/plugins/launchers";
 import { PluginSlotMount, PluginSlotOutlet, usePluginSlots } from "@/plugins/slots";
-import { Copy, FolderOpen, GitBranch, Loader2, Play, Square } from "lucide-react";
-import { IssuesQuicklook } from "../components/IssuesQuicklook";
+import { Loader2 } from "lucide-react";
 
 /* ── Top-level tab types ── */
 
@@ -211,7 +209,7 @@ function ProjectIssuesList({ projectId, companyId }: { projectId: string; compan
       projects={projects}
       liveIssueIds={liveIssueIds}
       projectId={projectId}
-      viewStateKey={`paperclip:project-view:${projectId}`}
+      viewStateKey="paperclip:project-issues-view"
       onUpdateIssue={(id, data) => updateIssue.mutate({ id, data })}
     />
   );
@@ -263,154 +261,21 @@ function ProjectWorkspacesContent({
   const activeSummaries = summaries.filter((summary) => summary.executionWorkspaceStatus !== "cleanup_failed");
   const cleanupFailedSummaries = summaries.filter((summary) => summary.executionWorkspaceStatus === "cleanup_failed");
 
-  const renderSummaryRow = (summary: ReturnType<typeof buildProjectWorkspaceSummaries>[number]) => {
-    const visibleIssues = summary.issues.slice(0, 5);
-    const hiddenIssueCount = Math.max(summary.issues.length - visibleIssues.length, 0);
-    const workspaceHref =
-      summary.kind === "project_workspace"
-        ? projectWorkspaceUrl({ id: projectRef, urlKey: projectRef }, summary.workspaceId)
-        : `/execution-workspaces/${summary.workspaceId}`;
-    const hasRunningServices = summary.runningServiceCount > 0;
-
-    const truncatePath = (path: string) => {
-      const parts = path.split("/").filter(Boolean);
-      if (parts.length <= 3) return path;
-      return `…/${parts.slice(-2).join("/")}`;
-    };
-
-    return (
-      <div
-        key={summary.key}
-        className="border-b border-border px-4 py-3 last:border-b-0"
-      >
-        {/* Header row: name + actions */}
-        <div className="flex items-center gap-3">
-          <Link
-            to={workspaceHref}
-            className="min-w-0 shrink truncate text-sm font-medium hover:underline"
-          >
-            {summary.workspaceName}
-          </Link>
-
-          <div className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
-            {summary.serviceCount > 0 ? (
-              <span className={`inline-flex items-center gap-1 ${hasRunningServices ? "text-emerald-500" : ""}`}>
-                <span className={`inline-block h-1.5 w-1.5 rounded-full ${hasRunningServices ? "bg-emerald-500" : "bg-muted-foreground/40"}`} />
-                {summary.runningServiceCount}/{summary.serviceCount}
-              </span>
-            ) : null}
-            {summary.executionWorkspaceStatus && summary.executionWorkspaceStatus !== "active" ? (
-              <span className="text-[11px] text-muted-foreground">{summary.executionWorkspaceStatus}</span>
-            ) : null}
-          </div>
-
-          <div className="ml-auto flex shrink-0 items-center gap-2">
-            <span className="text-xs text-muted-foreground">{timeAgo(summary.lastUpdatedAt)}</span>
-            {summary.hasRuntimeConfig ? (
-              <Button
-                variant="ghost"
-                size="sm"
-                className="h-7 gap-1.5 px-2 text-xs"
-                disabled={controlWorkspaceRuntime.isPending}
-                onClick={() =>
-                  controlWorkspaceRuntime.mutate({
-                    key: summary.key,
-                    kind: summary.kind,
-                    workspaceId: summary.workspaceId,
-                    action: hasRunningServices ? "stop" : "start",
-                  })
-                }
-              >
-                {runtimeActionKey === `${summary.key}:start` || runtimeActionKey === `${summary.key}:stop` ? (
-                  <Loader2 className="h-3 w-3 animate-spin" />
-                ) : hasRunningServices ? (
-                  <Square className="h-3 w-3" />
-                ) : (
-                  <Play className="h-3 w-3" />
-                )}
-                {hasRunningServices ? "Stop" : "Start"}
-              </Button>
-            ) : null}
-            {summary.kind === "execution_workspace" && summary.executionWorkspaceId && summary.executionWorkspaceStatus ? (
-              <Button
-                variant="ghost"
-                size="sm"
-                className="h-7 px-2 text-xs text-muted-foreground"
-                onClick={() => setClosingWorkspace({
-                  id: summary.executionWorkspaceId!,
-                  name: summary.workspaceName,
-                  status: summary.executionWorkspaceStatus!,
-                })}
-              >
-                {summary.executionWorkspaceStatus === "cleanup_failed" ? "Retry close" : "Close"}
-              </Button>
-            ) : null}
-          </div>
-        </div>
-
-        {/* Metadata lines: branch, folder */}
-        <div className="mt-1.5 space-y-0.5 text-xs text-muted-foreground">
-          {summary.branchName ? (
-            <div className="flex items-center gap-1.5">
-              <GitBranch className="h-3 w-3 shrink-0" />
-              <span className="font-mono">{summary.branchName}</span>
-            </div>
-          ) : null}
-          {summary.cwd ? (
-            <div className="flex items-center gap-1.5">
-              <FolderOpen className="h-3 w-3 shrink-0" />
-              <span className="truncate font-mono" title={summary.cwd}>
-                {truncatePath(summary.cwd)}
-              </span>
-              <CopyText text={summary.cwd} className="shrink-0" copiedLabel="Path copied">
-                <Copy className="h-3 w-3" />
-              </CopyText>
-            </div>
-          ) : null}
-          {summary.primaryServiceUrl ? (
-            <div className="flex items-center gap-1.5">
-              <a
-                href={summary.primaryServiceUrl}
-                target="_blank"
-                rel="noreferrer"
-                className="font-mono hover:text-foreground hover:underline"
-              >
-                {summary.primaryServiceUrl}
-              </a>
-            </div>
-          ) : null}
-        </div>
-
-        {/* Issues */}
-        {summary.issues.length > 0 ? (
-          <div className="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
-            <span className="font-medium text-muted-foreground/70">Issues</span>
-            {visibleIssues.map((issue) => (
-              <IssuesQuicklook key={issue.id} issue={issue}>
-                <Link
-                  to={`/issues/${issue.identifier ?? issue.id}`}
-                  className="font-mono hover:text-foreground hover:underline"
-                >
-                  {issue.identifier ?? issue.id.slice(0, 8)}
-                </Link>
-              </IssuesQuicklook>
-            ))}
-            {hiddenIssueCount > 0 ? (
-              <Link to={workspaceHref} className="hover:text-foreground hover:underline">
-                +{hiddenIssueCount} more
-              </Link>
-            ) : null}
-          </div>
-        ) : null}
-      </div>
-    );
-  };
-
   return (
     <>
       <div className="space-y-4">
         <div className="overflow-hidden rounded-xl border border-border bg-card">
-          {activeSummaries.map(renderSummaryRow)}
+          {activeSummaries.map((summary) => (
+            <ProjectWorkspaceSummaryCard
+              key={summary.key}
+              projectRef={projectRef}
+              summary={summary}
+              runtimeActionKey={runtimeActionKey}
+              runtimeActionPending={controlWorkspaceRuntime.isPending}
+              onRuntimeAction={(input) => controlWorkspaceRuntime.mutate(input)}
+              onCloseWorkspace={(input) => setClosingWorkspace(input)}
+            />
+          ))}
         </div>
         {cleanupFailedSummaries.length > 0 ? (
           <div className="space-y-2">
@@ -418,7 +283,17 @@ function ProjectWorkspacesContent({
               Cleanup attention needed
             </div>
             <div className="overflow-hidden rounded-xl border border-amber-500/20 bg-amber-500/5">
-              {cleanupFailedSummaries.map(renderSummaryRow)}
+              {cleanupFailedSummaries.map((summary) => (
+                <ProjectWorkspaceSummaryCard
+                  key={summary.key}
+                  projectRef={projectRef}
+                  summary={summary}
+                  runtimeActionKey={runtimeActionKey}
+                  runtimeActionPending={controlWorkspaceRuntime.isPending}
+                  onRuntimeAction={(input) => controlWorkspaceRuntime.mutate(input)}
+                  onCloseWorkspace={(input) => setClosingWorkspace(input)}
+                />
+              ))}
             </div>
           </div>
         ) : null}

ui/src/pages/ProjectWorkspaceDetail.tsx

@@ -7,6 +7,11 @@ import { Button } from "@/components/ui/button";
 import { Separator } from "@/components/ui/separator";
 import { ChoosePathButton } from "../components/PathInstructionsModal";
 import { projectsApi } from "../api/projects";
+import {
+  buildWorkspaceRuntimeControlSections,
+  WorkspaceRuntimeControls,
+  type WorkspaceRuntimeControlRequest,
+} from "../components/WorkspaceRuntimeControls";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
@@ -61,10 +66,6 @@ function readText(value: string | null | undefined) {
   return value ?? "";
 }
 
-function hasActiveRuntimeServices(workspace: ProjectWorkspace | null | undefined) {
-  return (workspace?.runtimeServices ?? []).some((service) => service.status === "starting" || service.status === "running");
-}
-
 function formatJson(value: Record<string, unknown> | null | undefined) {
   if (!value || Object.keys(value).length === 0) return "";
   return JSON.stringify(value, null, 2);
@@ -102,7 +103,7 @@ function parseRuntimeConfigJson(value: string) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {
         ok: false as const,
-        error: "Runtime services JSON must be a JSON object.",
+        error: "Workspace commands JSON must be a JSON object.",
       };
     }
     return { ok: true as const, value: parsed as Record<string, unknown> };
@@ -307,22 +308,24 @@ export function ProjectWorkspaceDetail() {
   });
 
   const controlRuntimeServices = useMutation({
-    mutationFn: (action: "start" | "stop" | "restart") =>
-      projectsApi.controlWorkspaceRuntimeServices(project!.id, routeWorkspaceId, action, lookupCompanyId),
-    onSuccess: (result, action) => {
+    mutationFn: (request: WorkspaceRuntimeControlRequest) =>
+      projectsApi.controlWorkspaceCommands(project!.id, routeWorkspaceId, request.action, lookupCompanyId, request),
+    onSuccess: (result, request) => {
       invalidateProject();
       setErrorMessage(null);
       setRuntimeActionMessage(
-        action === "stop"
-          ? "Runtime services stopped."
-          : action === "restart"
-            ? "Runtime services restarted."
-            : "Runtime services started.",
+        request.action === "run"
+          ? "Workspace job completed."
+          : request.action === "stop"
+            ? "Workspace service stopped."
+            : request.action === "restart"
+              ? "Workspace service restarted."
+              : "Workspace service started.",
       );
     },
     onError: (error) => {
       setRuntimeActionMessage(null);
-      setErrorMessage(error instanceof Error ? error.message : "Failed to control runtime services.");
+      setErrorMessage(error instanceof Error ? error.message : "Failed to control workspace commands.");
     },
   });
 
@@ -338,6 +341,16 @@ export function ProjectWorkspaceDetail() {
     return <p className="text-sm text-muted-foreground">Workspace not found for this project.</p>;
   }
 
+  const canRunWorkspaceCommands = Boolean(workspace.cwd);
+  const canStartRuntimeServices = Boolean(workspace.runtimeConfig?.workspaceRuntime) && canRunWorkspaceCommands;
+  const runtimeControlSections = buildWorkspaceRuntimeControlSections({
+    runtimeConfig: workspace.runtimeConfig?.workspaceRuntime ?? null,
+    runtimeServices: workspace.runtimeServices ?? [],
+    canStartServices: canStartRuntimeServices,
+    canRunJobs: canRunWorkspaceCommands,
+  });
+  const pendingRuntimeAction = controlRuntimeServices.isPending ? controlRuntimeServices.variables ?? null : null;
+
   const saveChanges = () => {
     const validationError = validateWorkspaceForm(form);
     if (validationError) {
@@ -532,14 +545,22 @@ export function ProjectWorkspaceDetail() {
                 </Field>
               </div>
 
-              <Field label="Runtime services JSON" hint="Default runtime services for this workspace. Execution workspaces inherit this config unless they set an override. If you do not know the commands yet, ask your CEO to configure them for you.">
-                <textarea
-                  className="min-h-36 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
-                  value={form.runtimeConfig}
-                  onChange={(event) => setForm((current) => current ? { ...current, runtimeConfig: event.target.value } : current)}
-                  placeholder={"{\n  \"services\": [\n    {\n      \"name\": \"web\",\n      \"command\": \"pnpm dev\",\n      \"cwd\": \".\",\n      \"port\": { \"type\": \"auto\" },\n      \"readiness\": {\n        \"type\": \"http\",\n        \"urlTemplate\": \"http://127.0.0.1:${port}\"\n      },\n      \"expose\": {\n        \"type\": \"url\",\n        \"urlTemplate\": \"http://127.0.0.1:${port}\"\n      },\n      \"lifecycle\": \"shared\",\n      \"reuseScope\": \"project_workspace\"\n    }\n  ]\n}"}
-                />
-              </Field>
+              <details className="rounded-xl border border-dashed border-border/70 bg-muted/20 px-3 py-3">
+                <summary className="cursor-pointer text-sm font-medium">Advanced runtime JSON</summary>
+                <p className="mt-2 text-sm text-muted-foreground">
+                  Paperclip derives Services and Jobs from this JSON. Prefer editing named commands first; use raw JSON for advanced lifecycle, port, readiness, or environment settings.
+                </p>
+                <div className="mt-3">
+                  <Field label="Workspace commands JSON" hint="Execution workspaces inherit this config unless they override it. Legacy `services` arrays still work, but `commands` supports both services and jobs.">
+                    <textarea
+                      className="min-h-96 w-full rounded-lg border border-border bg-background px-3 py-2 font-mono text-sm outline-none"
+                      value={form.runtimeConfig}
+                      onChange={(event) => setForm((current) => current ? { ...current, runtimeConfig: event.target.value } : current)}
+                      placeholder={"{\n  \"commands\": [\n    {\n      \"id\": \"web\",\n      \"name\": \"web\",\n      \"kind\": \"service\",\n      \"command\": \"pnpm dev\",\n      \"cwd\": \".\",\n      \"port\": { \"type\": \"auto\" },\n      \"readiness\": {\n        \"type\": \"http\",\n        \"urlTemplate\": \"http://127.0.0.1:${port}\"\n      },\n      \"expose\": {\n        \"type\": \"url\",\n        \"urlTemplate\": \"http://127.0.0.1:${port}\"\n      },\n      \"lifecycle\": \"shared\",\n      \"reuseScope\": \"project_workspace\"\n    },\n    {\n      \"id\": \"db-migrate\",\n      \"name\": \"db:migrate\",\n      \"kind\": \"job\",\n      \"command\": \"pnpm db:migrate\",\n      \"cwd\": \".\"\n    }\n  ]\n}"}
+                    />
+                  </Field>
+                </div>
+              </details>
             </div>
 
             <div className="mt-5 flex flex-col items-stretch gap-3 sm:flex-row sm:flex-wrap sm:items-center">
@@ -598,77 +619,27 @@ export function ProjectWorkspaceDetail() {
           <div className="rounded-2xl border border-border bg-card p-5">
             <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
               <div className="space-y-1">
-                <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Runtime services</div>
-                <h2 className="text-lg font-semibold">Attached services</h2>
+                <div className="text-xs font-medium uppercase tracking-[0.16em] text-muted-foreground">Workspace commands</div>
+                <h2 className="text-lg font-semibold">Services and jobs</h2>
                 <p className="text-sm text-muted-foreground">
-                  Shared services for this project workspace. Execution workspaces inherit this config unless they override it.
+                  Long-running services stay supervised here, while one-shot jobs run on demand against this workspace. Execution workspaces inherit this config unless they override it.
                 </p>
               </div>
-              <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:flex-wrap">
-                <Button
-                  variant="outline"
-                  size="sm"
-                  className="w-full sm:w-auto"
-                  disabled={controlRuntimeServices.isPending || !workspace.runtimeConfig?.workspaceRuntime || !workspace.cwd}
-                  onClick={() => controlRuntimeServices.mutate("start")}
-                >
-                  {controlRuntimeServices.isPending ? <Loader2 className="mr-2 h-3.5 w-3.5 animate-spin" /> : null}
-                  Start
-                </Button>
-                <Button
-                  variant="outline"
-                  size="sm"
-                  className="w-full sm:w-auto"
-                  disabled={controlRuntimeServices.isPending || !workspace.cwd}
-                  onClick={() => controlRuntimeServices.mutate("restart")}
-                >
-                  Restart
-                </Button>
-                <Button
-                  variant="outline"
-                  size="sm"
-                  className="w-full sm:w-auto"
-                  disabled={controlRuntimeServices.isPending || !hasActiveRuntimeServices(workspace)}
-                  onClick={() => controlRuntimeServices.mutate("stop")}
-                >
-                  Stop
-                </Button>
-              </div>
             </div>
-            <Separator className="my-4" />
-            {workspace.runtimeServices && workspace.runtimeServices.length > 0 ? (
-              <div className="space-y-3">
-                {workspace.runtimeServices.map((service) => (
-                  <div key={service.id} className="rounded-xl border border-border/80 bg-background px-3 py-2">
-                    <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-                      <div className="space-y-1">
-                        <div className="text-sm font-medium">{service.serviceName}</div>
-                        <div className="space-y-1 text-xs text-muted-foreground">
-                          {service.url ? (
-                            <a href={service.url} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 hover:underline">
-                              {service.url}
-                              <ExternalLink className="h-3 w-3" />
-                            </a>
-                          ) : null}
-                          {service.port ? <div>Port {service.port}</div> : null}
-                          <div>{service.command ?? "No command recorded"}</div>
-                          {service.cwd ? <div className="break-all font-mono">{service.cwd}</div> : null}
-                        </div>
-                      </div>
-                      <div className="text-[11px] uppercase tracking-[0.14em] text-muted-foreground sm:text-right">
-                        {service.status} · {service.healthStatus}
-                      </div>
-                    </div>
-                  </div>
-                ))}
-              </div>
-            ) : (
-              <p className="text-sm text-muted-foreground">
-                {workspace.runtimeConfig?.workspaceRuntime
-                  ? "No runtime services are currently running for this workspace."
-                  : "No runtime-service default is configured for this workspace yet."}
-              </p>
-            )}
+            <WorkspaceRuntimeControls
+              className="mt-4"
+              sections={runtimeControlSections}
+              isPending={controlRuntimeServices.isPending}
+              pendingRequest={pendingRuntimeAction}
+              serviceEmptyMessage={
+                workspace.runtimeConfig?.workspaceRuntime
+                  ? "No services have been started for this workspace yet."
+                  : "No workspace command config is defined for this workspace yet."
+              }
+              jobEmptyMessage="No one-shot jobs are configured for this workspace yet."
+              disabledHint="Project workspaces need a working directory before local commands can run, and services also need runtime config."
+              onAction={(request) => controlRuntimeServices.mutate(request)}
+            />
           </div>
         </div>
       </div>