User Flow Map — Personal Workstation

Alignment Status: review · Tier: prototype · Category: product-design · Skill: user-flow-map · Date: 2026-06-17

Summary. This is a review (pre-approval) alignment page for a redo-from-scratch user flow map of the gblock-party personal workstation — the single-user dogfood environment for managed, always-on AI coding agents. It maps entry points, a happy path (S1→Ship), seven named alternate-path branch roots, eight decision points (D1–D8), a ten-screen inventory (S1–S10), per-screen action/state matrices, failure/recovery, handoffs, and low-fidelity wireframe notes.

The canonical artifacts have already been written to design/ and the user confirmed assumptions ("looks good to me") and coverage conversationally. The gates below ask you to confirm those already-written artifacts. Two material changes since the prior version: (1) Claude Code ToS is now resolved — Anthropic permits subscription use from third-party apps (2026-06-17), so Claude Code is first-class with no asterisk; and (2) output location was corrected from specs/ to design/.

✓ Alignment Confirmed

alignment_status: confirmed
Confirmed: 2026-06-18
Approval source: Compiled response YAML — approval_status: ready-for-agent-review, required_gate_status: complete, all 8 gates answered (Gates 1–6 confirmed-as-written, Gate 7 approved-as-written, Gate 8 stop-clear-context), no section feedback.
Confirmed artifacts: design/user-flow-personal-workstation.md, design/user-flow-personal-workstation-interview.md, design/flow-tree-personal-workstation.yaml.
Downstream route (Gate 8): stop / clear context — user starts /ux-variations [branch] in a fresh session.

This page is current for the completed alignment cycle. It is finished but amendable: later research can amend it only by archiving this confirmed page first and highlighting what changed. Confirmed means approved/current, not immutable.

1. Scope & Context

Product: gblock-party personal workstation — the single-user dogfood environment for gblock-party's managed always-on agent infrastructure.
Goal: Replace the SSH → tmux → Tailscale → per-tool ceremony with one-click agent management from any device.
Persona: Solo developer, "The Agent Conductor," running 5–12 AI coding agents across 1–3 repos on managed infrastructure.
Success condition: Agents run persistently on managed infrastructure, controllable from any device with session persistence — the "closed laptop, checked from phone, 3 PRs ready" aha moment.
Mode: Flat (single-product). Topic: personal-workstation.
Source evidence: research/positioning.md, research/journey-map.md, research/icp.md, research/concept-brief-gblock-party-personal.md, research/_working/preliminary-user-flow-map-research.md.

Redo-from-scratch rebuild. Supersedes the prior flow map that was written to specs/ (incorrect location — pre-prototype flow maps are canonical under design/). Prior copies archived under docs/history/archive/2026-06-17/104712/.

Explicit Non-Goals

High-fidelity UI design, component styling, or design-system decisions.
Production architecture, database schemas, or implementation plans.
IDE-dependent tool integrations (Windsurf, Tabnine) — require a desktop IDE runtime, not viable headless.
Multi-tenant / team features (personal-workstation scope only).
Billing, payments, or subscription management.

2. Assumptions Checkpoint

Confirmed Assumptions

[from positioning] Primary user is a solo developer who wants persistent, always-on AI coding agent sessions accessible from any device.
[from positioning] Competitive alternative is DIY tmux + SSH + VPS + Tailscale, not other managed tools.
[from journey-map] Aha moment is "closed laptop, checked from phone, 3 PRs ready."
[from journey-map] Mobile approval routing is a core differentiator, not a nice-to-have.
[user-confirmed] Personal workstation is the first product; the SaaS control plane comes later.
[from concept-brief] BYO-client model: users connect their own front-end tools and bring their own model subscriptions/keys (end-to-end connectivity validation still needed — load-bearing, see Open Questions #6).
[user-confirmed] Authentication enforces GitHub OAuth — provides identity verification and grants repo access (pull, push, PR creation) so agents can operate on the user's repositories as approved.
[inferred] Initial tool support covers all headless-viable tools (8 tools, per the integration patterns below).
[inferred] The dashboard is a PWA for installability on mobile and desktop.
[user-confirmed] A QR code displayed on desktop/terminal/web clients enables fast mobile handoff — it encodes a pre-authenticated deep link so the phone opens directly to the current view without manual login.
[from positioning] Zero-inbound networking (Tailscale/WireGuard tunnel) is a table-stakes security requirement.

Assumptions Needing Validation

[inferred] xterm.js terminal can achieve sub-100ms latency over the encrypted tunnel to the managed backend from typical US locations.
[inferred] code-server (Mode C) is worth the complexity for MVP, or should be deferred.
[inferred] Multica-style stdout parsing is reliable enough for structured status extraction across all tools.

Gate 1: Flow Assumptions approved

The assumptions above are already written into design/user-flow-personal-workstation.md, and you confirmed them conversationally ("looks good to me"). Please confirm the written record.

Are the confirmed and needs-validation assumptions accurately captured as written?

Decision: Yes — confirmed as written

3. Technical Architecture

Workflow-level context only. These notes establish what surfaces the flow connects to; they are not implementation specs.

Tool Integration Patterns

Pattern	Examples	Integration Method	Notes
API-native	Claude Agent SDK	REST API, server-side sessions	Cleanest integration; direct programmatic control. First-class — no ToS caveat (see below).
Headless CLI with daemon	Codex CLI (remote-control / app-server), Cursor (agent worker start)	Daemon on managed backend, Unix socket/URL task submission	Built-in remote capabilities; moderate integration effort.
Headless CLI (process mgmt)	Claude Code CLI, Aider, Continue (cn), Cline CLI, Copilot CLI, Augment (auggie)	Process supervision, stdout capture	Multica-style stdout parsing; works with any CLI tool.
IDE-dependent	Windsurf, Tabnine	Requires desktop IDE runtime	Not viable for headless backend — out of scope.

Claude Code ToS — resolved (2026-06-17)

Per a recent Anthropic announcement, Claude Code subscriptions are now usable from third-party applications. Claude Code CLI and the Claude Agent SDK are therefore first-class supported BYO-client tools with no ToS asterisk and no deferral. The architecture framing is unchanged: gblock-party runs on the user's managed VM with the user's own subscription; the Agent Board is a router/connector, never a proxy — it never touches API keys or model traffic.

Session Persistence by Tool

Tool	Resume?	State Location	Best Integration
Codex CLI	Yes (`codex resume <id>`)	`~/.codex/sessions/`	remote-control daemon + Unix socket
Claude Agent SDK	Yes (API-native)	Server-side	Direct REST API
Claude Code CLI	Yes (`--continue`, `--resume <id>`)	`~/.claude/projects/` JSONL	Process mgmt + `--resume`
Cursor	Yes (headless worker)	Worker-managed	`agent worker start` + URL
Aider	No built-in	Git commits as checkpoints	Process mgmt
Continue (cn)	Yes (`cn --resume`)	`~/.continue/sessions/` JSON	Process mgmt + `--resume`
Cline CLI	Partial (cron persists)	Config-shared with IDE	Process mgmt + MCP
Copilot CLI	Yes (`/memory`, `/chronicle`)	GitHub-managed	Process mgmt + prompt mode

Access Mode Architecture

Mode A — Dashboard Router

Status cards, approval queue, async recap. Multica-style stdout parsing for real-time status. Low latency, mobile-friendly. Primary interface for monitoring and quick interactions.

Mode B — Terminal Drill-Down

Full xterm.js terminal via WebSocket to the tmux session. Sub-100ms keystroke echo target. For interactive debugging, manual commands, and deep agent interaction. Desktop-optimized.

Mode C — Code-Server IDE

VS Code in the browser via code-server. Desktop-replacement experience for extended sessions. Full editor capabilities without a local IDE. Highest resource cost — MVP ROI is an open question.

4. Entry Points & Preconditions

Entry Point	Precondition	Routes To
Open PWA URL (first visit)	None	S2 Setup Wizard
Open PWA URL (returning)	Config exists, session valid	S3 Agent Board
Open PWA URL (session expired)	Config exists, session expired	S1 GitHub Auth
Push notification tap	PWA installed, push subscription active	S7 Approval or S3 Board
QR code scan from desktop	Desktop client showing QR code	S1 auto-auth via one-time token → target view
PWA home-screen icon	PWA installed	S1 or S3 depending on session

5. Happy Path

Interactive preview — ephemeral, not production code

Walk the primary journey from opening the app to shipping code. Use Next / Prev to step through, or click any step. Requires JavaScript; with JS disabled, the full numbered list below is the fallback.

Open PWA/CLI

→

[S1] GitHub Auth

→

[S3] Agent Board

→

[S4] Start Agent

→

[S3] New Card

→

[S5/S6] Interact

→

[S7] Approval

→

Close Laptop

→

[S3] Resume

→

[S8] Recap

→

[S9] Diff Review

→

Ship

Open PWA/CLI — The app detects authentication state and routes accordingly.

[S1] GitHub Auth — GitHub OAuth login; identity + repo scopes; session persists across devices.

[S3] Agent Board — Grid of agent cards with status, task, repo, elapsed time, token usage; approval-queue badge.

[S4] Start Agent — One-click modal: select repo, tool, initial prompt. Agent starts immediately.

[S3] New Card — New card "starting" → "running"; real-time stdout preview begins.

[S5/S6] Interact — Structured output (Mode A) or full terminal (Mode B).

[S7] Approval — Agent requests approval; push to all devices; compact approval card with diff.

Close Laptop — Agents continue on managed infrastructure; no interruption.

[S3] Resume — Open from a new device; same board, same state; no reconnection ceremony.

[S8] Recap — Summary of completed tasks, pending approvals, errors, PRs created.

[S9] Diff Review — Full diff viewer; approve, request changes, or merge; GitHub PR flow.

Ship — Merge the PR, deploy, or queue the next task. The cycle repeats.

Gate 2: Proposed Flow Map approved

The happy path and entry points are already written into design/user-flow-personal-workstation.md. Please confirm the proposed flow map as written.

Does the proposed flow map (entry points + happy path S1→Ship) correctly represent the intended primary journey?

Decision: Yes — flow map confirmed as written

6. Alternate Paths (Branch Roots)

Each lettered path is a named user-flow branch and a candidate root for /ux-variations [flow]. They are not collapsed into a single standard flow. Click each card to expand.

A. First-Time Setup onboarding

▼

Install PWA / open URL for the first time.
[S2] Setup Wizard — GitHub OAuth login (repos auto-discovered), connect model-provider keys/subscriptions, set notification preferences.
Provision infrastructure — gblock-party provisions managed infrastructure automatically.
Health check — verify connectivity, tool availability, GitHub repo access via OAuth token.
[S10] Setup summary — review and save configuration.
Redirect to [S3] Agent Board — empty board with "Start your first agent" prompt.

B. Phone Quick-Check phone-check

▼

Push notification — "Agent needs approval" or "3 tasks completed."
Tap notification — opens the PWA directly to the relevant screen.
[S1] Auto-auth — GitHub OAuth session persists; instant reconnect on mobile.
[S7] Approval card — compact mobile-optimized view with diff summary.
Approve/reject — one-tap action, agent resumes immediately.
Close app — total time under 30 seconds.

C. Parallel Sprint parallel-sprint

▼

[S3] Agent Board — view existing running agents.
[S4] Start Agent #2 — launch a second agent on a different repo/branch.
[S4] Start Agent #3 — launch a third agent on yet another task.
[S3] Monitor all — board shows 3+ cards, each with live status.
Round-robin approvals — handle approval requests as they arrive from different agents.
[S9] Review diffs — review completed work from each agent sequentially.
Ship all — merge PRs, handle any conflicts between agent outputs.

D. Agent Recovery recovery

▼

[S3] Agent card shows error — red status badge, error summary visible.
[S5] Click into agent — view full error output, stack trace, last successful state.
Decision: retry or intervene — one-click retry with the same prompt, or drop to terminal.
[S6] Terminal mode — if manual intervention is needed, full terminal access.
Fix and restart — resolve the issue, restart the agent with an adjusted prompt.
[S3] Agent resumes — card transitions back to running.

E. Session Handoff / Device Switch device-handoff

▼

Working on laptop — active terminal session with agent in Mode B.
Need to leave — close the laptop lid or navigate away.
Agent continues — backend process is unaffected by client disconnect.
Open on phone — PWA opens via bookmark, push notification, or QR code scan from the desktop client.
[S3] Same board state — all agents show current status, no stale data.
[S8] Recap available — summary of activity since the last interaction from the previous device.

F. QR Code Mobile Handoff qr-handoff

▼

User on desktop client — working in the desktop app, web dashboard, or terminal client.
Wants mobile access — clicks "Open on Mobile" or finds the QR code in the header/settings.
QR code displayed — encodes a short-lived, pre-authenticated deep link to the current view (board, specific agent, or approval queue).
Scan with phone camera — the standard OS camera app recognizes the URL.
[S1] Auto-auth — deep link carries a one-time token; GitHub OAuth session established on mobile without manual login.
[S3] or [S7] Context preserved — phone opens to the same screen the user was viewing, or directly to a pending approval.
PWA install prompt — if first mobile visit, prompt to install the PWA for future push notifications and home-screen access.

G. Update Settings settings

▼

[S10] Settings — navigate to settings from the board.
Update tool configuration — add/remove tools, update keys, re-authorize GitHub OAuth scopes.
Health check — verify the new configuration works.
Optional re-provision — if adding a new tool, run provisioning for that tool only.
Return to [S3] — board reflects new capabilities.

7. Flow-Tree Manifest

Manifest at design/flow-tree-personal-workstation.yaml — schema_version: v0.1, mode: flat, topic: personal-workstation. Route: user-flow-map → ux-variations → ui-interview → prototype → consolidate-variations → spec-interview. One entry per named user-flow branch (wireframe-tree root); each is a candidate root for /ux-variations [branch_id].

Branch ID	Name	Flow Paths	Screens	Description	ux_variations	Decision
`onboarding`	First-Time Setup	A	S1, S2, S10, S3	GitHub OAuth, provisioning, tool/key config, health check, setup summary, empty board.	not-started	pending
`monitoring-start`	Board Monitoring & One-Click Start	happy-path, C	S3, S4, S5, S6	Agent Board overview, one-click agent start, parallel sprints, live status.	not-started	pending
`approval`	Mobile Approval Routing	B	S7, S3	Push-triggered approval, compact mobile card, one-tap approve/reject/defer, approval queue.	not-started	pending
`recovery`	Agent Error Recovery	D	S3, S5, S6	Error state, drill-in, retry vs. terminal intervention, restart.	not-started	pending
`device-handoff`	Cross-Device Continuity & QR Handoff	E, F	S1, S3, S7, S8	Server-canonical state across devices; QR pre-authenticated deep link; async recap on return.	not-started	pending
`diff-review`	Diff Review & Ship	happy-path	S9, S3	Completed-work diff viewer, approve/changes/discard, PR creation to GitHub.	not-started	pending
`settings`	Settings & Configuration	G	S10, S3	Tool/key management, notification prefs, OAuth scopes, optional re-provision.	not-started	pending

Source artifacts: research/positioning.md, research/journey-map.md, research/icp.md, research/concept-brief-gblock-party-personal.md, research/_working/preliminary-user-flow-map-research.md. Artifacts: flow_map: design/user-flow-personal-workstation.md, interview_log: design/user-flow-personal-workstation-interview.md, alignment_page: alignment/user-flow-map-personal-workstation.html.

Gate 3: Branch & Decision Coverage approved

The seven branch roots and the D1–D8 decision points (Section 8) are already written into design/ and the manifest. You confirmed coverage conversationally. Please confirm the written record.

Do the 7 named branch roots and 8 decision points cover the intended flows and choice points?

Decision: Yes — coverage confirmed as written

8. Decision Points (D1–D8)

#	Decision	Who Decides	Options	Branch To
D1	First visit or returning?	System (auto-detect)	No config → Setup Wizard; config exists → Auth	S2 or S1
D2	Which access mode?	User (explicit)	Dashboard (A), Terminal (B), IDE (C)	S3 / S6 / code-server
D3	Start new agent or interact with existing?	User	Start new → S4 modal; click existing → S5/S6	S4 or S5/S6
D4	Agent requests approval	User	Approve, reject, modify prompt, defer	Agent resumes, retries, or pauses
D5	Agent encounters error	System + User	Auto-retry (transient), alert user (persistent), stop agent	Retry loop, S7 alert, or S3 error state
D6	Review completed work	User	Approve diff, request changes, discard	S9 → Ship, S9 → new task, or archive
D7	Device switch detected	System (auto-detect)	Show recap if time gap > threshold, else resume live	S8 recap or S3 live board
D8	Multiple agents need approval simultaneously	User	Queue (FIFO), priority sort, batch approve	S7 approval queue or batch action

9. Screen/Route Inventory (S1–S10)

S1 — GitHub OAuth Authentication

Purpose: Verify identity and grant repo-access scopes for agent operations.
Inputs: GitHub OAuth flow (redirect to GitHub, user authorizes scopes).
Outputs: Authenticated session token + GitHub access token (repo read/write, PR creation, branch management).
Source: [user-confirmed] GitHub OAuth enforced for identity + repo access.
Access Mode: All (entry point).
Downstream: S3 (returning) or S2 (first visit) or target deep-link view.

S2 — Setup Wizard

Purpose: First-time account setup and tool configuration.
Inputs: Model-provider keys/subscriptions, notification preferences (repos auto-discovered via GitHub OAuth token).
Outputs: Managed workspace provisioned with tools ready and connectivity verified.
Source: [from journey-map] onboarding flow.
Access Mode: A (Dashboard).
Downstream: S10 setup summary → S3.

S3 — Agent Board

Purpose: Central dashboard showing all agents, their status, and the approval queue.
Inputs: Real-time agent status via WebSocket, approval notifications.
Outputs: Navigation to agent details, start-agent modal, approval actions.
Source: [from positioning] unified visibility as core differentiator.
Access Mode: A (Dashboard) — primary interface.
Downstream: S4, S5/S6, S7, S8, S9, S10.

S4 — Start Agent Modal

Purpose: One-click agent launch with repo, tool, and prompt selection.
Inputs: Repository picker (auto-populated from GitHub OAuth), tool selector, initial prompt, optional branch.
Outputs: New agent process started, card added to S3.
Source: [from positioning] "one-click replaces SSH ceremony."
Access Mode: A (Dashboard) — modal overlay.
Downstream: S3 (new card).

S5 — Agent Detail (Structured)

Purpose: Parsed, structured view of agent output and progress.
Inputs: Multica-style parsed stdout, task progress, file changes.
Outputs: Approval actions, prompt injection, stop/restart controls.
Source: [inferred] dashboard-native agent interaction.
Access Mode: A (Dashboard).
Downstream: S6 (terminal escalation), S7 (inline approval), S9 (diff).

S6 — Agent Terminal

Purpose: Full interactive terminal session with the running agent.
Inputs: WebSocket connection to the tmux session, keyboard input.
Outputs: Raw terminal output, command execution.
Source: [inferred] power-user escape hatch.
Access Mode: B (Terminal).
Downstream: S5 (back to structured), S3.

S7 — Approval Request

Purpose: Present the agent's decision point for approval/rejection.
Inputs: Diff preview, agent explanation, proposed action, risk assessment.
Outputs: Approve, reject, modify, or defer decision.
Source: [from journey-map] smart approval routing.
Access Mode: A (Dashboard) — mobile-optimized.
Downstream: Agent process (resume), S3, next approval in queue.

S8 — Async Recap

Purpose: Summary of agent activity during the user's absence.
Inputs: Time-windowed activity log, completed tasks, pending items.
Outputs: Navigation to relevant agents, diffs, or the approval queue.
Source: [from journey-map] device-switch continuity.
Access Mode: A (Dashboard).
Downstream: S3, S7, S9.

S9 — Diff Review

Purpose: Full diff viewer for completed agent work and PR creation.
Inputs: Git diff, file tree, commit history from the agent session.
Outputs: Approve and merge, request changes, create PR.
Source: [inferred] ship step in the flow.
Access Mode: A (Dashboard) or C (IDE).
Downstream: GitHub (external), S3, S4 (next task).

S10 — Settings

Purpose: Configure tools, keys, notifications, and preferences; also serves the setup summary.
Inputs: Configuration values, keys, notification preferences.
Outputs: Updated configuration, re-provisioning if needed.
Source: [inferred] ongoing configuration management.
Access Mode: A (Dashboard).
Downstream: S3.

10. Per-Screen Action/State Matrix

S3 — Agent Board

State	Trigger	Display	Available Actions	Disabled/Blocked
Empty	No agents configured or all stopped	Empty state, "Start your first agent" CTA + quick-start guide	Start agent, open settings	Approval/diff actions hidden
All Running	All agents actively processing	Grid of green-badged cards w/ live stdout preview, elapsed time	Open agent, start agent, stop	—
Mixed Status	Some running, some idle/waiting/error	Cards sorted: error > waiting > running > idle	Open any agent, triage approvals	—
Approval Pending	One+ agents waiting	Approval-queue badge in header; waiting cards pulsate subtly	Open approval, batch approve	—
All Complete	All agents finished	Cards show completion summary, "Review diffs" CTA prominent	Review diffs, start agent	—
Connection Lost	WebSocket drops	Banner: "Reconnecting to workspace…" w/ auto-retry; last-known state shown	View last-known state	Start/stop disabled until reconnect

S4 — Start Agent

State	Trigger	Display	Available Actions	Disabled/Blocked
Ready	Modal opened, repos + tools loaded	Repo picker, tool selector, prompt textarea, "Start" enabled	Start, cancel	Start disabled until repo+tool+prompt set
Loading Repos	Fetching repo list	Skeleton loaders in repo picker, other fields disabled	Cancel	All inputs disabled
Launching	User clicked Start	Spinner on button, fields disabled, "Starting agent…"	—	All inputs disabled
Error	Launch failed (tool not found, git error)	Error message w/ retry, fields re-enabled	Retry, cancel	—
Tool Unavailable	Selected tool not in workspace	Warning w/ "Install tool" link to S10	Install tool → S10, pick another tool	Start disabled

S5 — Agent Detail (Structured)

State	Trigger	Display	Available Actions	Disabled/Blocked
Streaming	Agent actively producing output	Live parsed output, progress indicators, file-change list updating	Inject prompt, stop, open terminal	—
Waiting for Input	Agent paused for approval/input	Inline approval card, prompt-injection textarea	Approve/reject, inject prompt	—
Idle	Task finished, awaiting next	Completion summary, "Assign next task" CTA	New task, review diff	—
Error	Agent crashed / fatal error	Error details, stack trace if available	Retry, restart, open terminal	—
Reconnecting	WebSocket dropped mid-stream	"Reconnecting…" overlay; buffered output replays on reconnect	Wait, retry	Inject/stop disabled until reconnect

S6 — Agent Terminal

State	Trigger	Display	Available Actions	Disabled/Blocked
Connecting	WebSocket handshake	"Connecting to session…"	Cancel/back	Input disabled
Active	Terminal stream live	Full xterm.js terminal	Type commands, key input, back to board	—
Waiting for Approval	Agent blocked	Terminal + overlay/badge for pending approval	Approve inline, continue typing	—
Disconnected	WebSocket dropped	"Reconnecting…" w/ auto-retry; tmux preserves state	Wait, manual retry	Input disabled until reconnect
Completed	Agent finished	Terminal output + "Session complete" banner	Restart, back to board	—

S7 — Approval Request

State	Trigger	Display	Available Actions	Disabled/Blocked
Pending	Agent requested approval, no action yet	Diff preview, approve/reject buttons, wait-duration timer	Approve, reject, modify, defer, expand	—
Reviewing	User expanded full diff/context	Full diff viewer, file tree, agent explanation	Approve, reject w/ reason, collapse	—
Approved	User approved	Brief "Approved" confirmation; auto-return to S3 or next approval	— (auto-advances)	—
Rejected	User rejected w/ optional feedback	Rejection-reason textarea; agent receives feedback	Submit reason	—
Expired	Configurable timeout elapsed	Grayed card; still-approve option or auto-rejected per settings	Approve late (if allowed)	Approve disabled if auto-rejected

S8 — Async Recap

State	Trigger	Display	Available Actions	Disabled/Blocked
Activity Summary	User returns after absence > threshold	Timeline: tasks completed, approvals pending, errors, PRs created	Open item, dismiss	—
Nothing New	User returns but agents were idle	"All quiet" message	Go to board	—
Urgent Items	Errors or expired approvals during absence	Urgent items highlighted at top, sorted by priority	Resolve urgent, dismiss	—
Dismissed	User closes recap	Redirect to S3; recap accessible from history menu	Reopen from history	—

Gate 4: State Coverage approved

The per-screen action/state matrices for S3, S4, S5, S6, S7, S8 are already written into design/. Please confirm the written record.

Are the per-screen states, triggers, actions, and blocked actions sufficient and accurate?

Decision: Yes — state coverage confirmed as written

11. Failure & Recovery Paths

Failure	Detection	Recovery
Backend unreachable	WebSocket heartbeat timeout (>10s), health-check failure	Auto-reconnect w/ exponential backoff. Banner notification. Agents continue on managed infra if client-side issue; if backend down, show last-known state and alert.
Agent process crash	Process supervisor detects exit code ≠ 0	Auto-restart for transient errors (up to 3 retries). Log crash details. Notify user w/ error summary. Offer manual restart or terminal access.
Network tunnel drop	Connectivity monitor on backend and client	Tunnel auto-reconnect. Dashboard shows "Tunnel reconnecting…". Agents unaffected (running on managed infra).
Model key/subscription expiry or rate limit	Agent reports auth or rate-limit error	Pause agent, notify user. Link to S10 to update credential. Resume agent after update without losing session state.
GitHub OAuth token expired/revoked	Agent git operation returns 401/403	Pause affected agents, prompt re-auth via GitHub OAuth. Resume automatically once a new token is issued. No session state lost.
Disk space exhaustion	Monitoring daemon checks disk usage > 90%	Alert before critical. Suggest cleanup (old sessions, build artifacts). Emergency: pause agents to prevent corruption.
Git conflict during agent work	Agent's git operation fails w/ merge conflict	Agent pauses and requests approval w/ conflict details. User resolves via S6 terminal or instructs agent to resolve.
Browser/PWA crash	Service worker detects unclean shutdown on next load	Agents unaffected (server-side). PWA reloads to S3 w/ current state. No data loss.
Concurrent device conflict	Same agent interacted with from two devices simultaneously	Last-write-wins for approvals. Terminal sessions are separate tmux windows. Dashboard state eventually consistent via WebSocket.

12. Handoffs

From	To	Mechanism	Notes
S3 Agent Board	S5/S6 Detail/Terminal	Click card; WebSocket attaches to agent's tmux session or stdout stream	Seamless; output buffers replayed on connect.
S7 Approval	Agent process (backend)	Approval message via internal API to agent stdin/control socket	Sub-second delivery; agent resumes immediately.
S4 Start Agent	Backend process supervisor	REST API call; supervisor spawns tool process	Process isolation per agent; resource limits applied.
Device A (laptop)	Device B (phone)	Shared server state; new WebSocket from Device B reads same state	No explicit handoff needed; state is server-canonical. QR provides fast first-connect path.
Desktop client (QR)	Mobile PWA	QR encodes short-lived pre-authenticated deep link; phone camera scans, opens PWA	One-time token avoids manual OAuth on mobile. Deep link targets current view. Falls back to S1 if token expired.
S9 Diff Review	GitHub (external)	Git push from backend; PR creation via GitHub API	Agent can auto-create PR; user reviews/merges from S9 or GitHub directly.
Push notification	S7 Approval	Deep link in push opens PWA directly to approval card	Requires PWA service worker + push subscription; falls back to S3 if deep link fails.

Gate 5: Failure/Recovery & Handoff Coverage approved

The failure/recovery table (9 scenarios) and handoffs table (7 handoffs) are already written into design/. Please confirm the written record.

Do the failure/recovery and handoff tables cover the important failure modes and transitions?

Decision: Yes — coverage confirmed as written

13. Low-Fidelity Wireframe Notes

Structural only — regions and groupings, not styling.

S3 — Agent Board

Header: App name, approval-queue badge count, settings gear, QR / "Open on Mobile" button.
Primary content: Responsive grid of agent cards (2–3 columns desktop, 1 column mobile).
Card layout: Agent name, status badge, tool name, repo, elapsed time, one-line stdout preview.
Card sorting: error > waiting > running > idle.
Empty state: Centered illustration + "Start your first agent" CTA + quick-start link.
Connection lost: Top banner with reconnecting animation.

S4 — Start Agent Modal

Overlay: Centered modal with backdrop.
Fields: Repo picker (dropdown, auto-populated), tool selector (dropdown), initial prompt (textarea), optional branch.
Actions: "Start Agent" primary, "Cancel" secondary.
Validation: All required fields filled before Start enables.

S5 — Agent Detail (Structured)

Header: Agent name, tool, repo, status, elapsed time; "Open Terminal" toggle to Mode B.
Primary content: Parsed activity stream (steps, file changes); progress indicator.
Inline approval: Approval card appears in-flow when the agent is waiting.
Footer: Prompt-injection textarea, stop/restart controls.

S6 — Agent Terminal

Top bar: Agent name, tool, repo, status, session duration; "Back to Board".
Primary content: Full-width xterm.js terminal.
Side/bottom bar: Approval-queue count, quick-approve button if pending.

S7 — Approval Request (Mobile-Optimized)

Compact card: Agent name, wait duration, one-line description, risk badge.
Diff preview: 3–5 lines of context, expandable to full diff + file tree.
Actions: Large tap targets — Approve (green), Reject (red), Defer (gray).
Rejection flow: Expand textarea for rejection reason.

S8 — Async Recap

Timeline layout: Vertical list of events since last interaction.
Event types: Task completed, approval pending, error occurred, PR created.
Urgent items: Highlighted at top with distinct styling.
Dismiss: "Got it" returns to S3.

S9 — Diff Review

Split layout: File tree left, diff viewer right (desktop); stacked on mobile.
Actions: Approve and merge, request changes, create PR.
Navigation: File-by-file navigation, jump to changes.

S10 — Settings

Sections: Tools & keys, notifications, GitHub OAuth scopes, infrastructure status.
Health check: Per-tool connectivity indicator.
Danger zone: Reset workspace, revoke access.

Gate 6: Low-Fidelity Wireframe Notes approved

The structural wireframe notes for S3–S10 are already written into design/ (regions/groupings only, no styling). Please confirm the written record.

Are the low-fidelity wireframe region/grouping notes at the right altitude and complete?

Decision: Yes — wireframe notes confirmed as written

14. Open Questions & Risks

xterm.js latency budget: Can sub-100ms keystroke echo be achieved from a US-based user to the managed backend? If not, should Mode B be deprioritized for MVP in favor of structured output only?
Multica stdout-parsing reliability: How well does the parsing pattern generalize across Codex CLI, Aider, and other tools with different output formats? Do we need per-tool parsers?
Push notification reliability on mobile: Web Push support varies by platform (iOS Safari limitations). Reliable enough for approval routing, or do we need a fallback (SMS, Telegram bot, email)?
code-server (Mode C) ROI for MVP: code-server adds significant complexity (resource usage, extension compatibility, security surface). Defer to post-MVP, or essential for the "desktop replacement" positioning?
Agent resource isolation: Running 5–12 agents simultaneously — memory/CPU requirements? cgroups/containers per agent, or is process-level isolation sufficient for a personal workstation?
BYO-client connectivity validation: Can popular front-end tools (Cursor, Claude Code CLI, Codex CLI) actually connect to a managed backend without custom adapters? Tools with hardcoded endpoints or locked inference layers may require protocol adapters. Load-bearing — the entire BYO-client model depends on it.

Resolved since prior version

Claude Code ToS compliance is no longer an open question — Anthropic now permits subscription use from third-party applications (2026-06-17). Claude Code is a first-class supported tool.

15. Downstream Handoff

The normal AFPS route is /user-flow-map → /ux-variations [specific-user-flow] → /ui-interview [specific-ux-variation].

Branch roots available for /ux-variations (see flow-tree manifest for IDs):

onboarding (Path A) — first-time setup and provisioning.
monitoring-start (Happy path + Path C) — board monitoring and one-click agent start.
approval (Path B + S7) — mobile approval routing.
recovery (Path D) — agent error recovery.
device-handoff (Paths E + F) — cross-device continuity and QR handoff.
diff-review (S9) — completed-work review and ship.
settings (Path G) — configuration management.

This flow-map approval authorizes the wireframe-tree root and provides source evidence. It does not approve any UX variation branch, visual mockup, UI proposal, or implementation path, and it does not count as ui-interview completion. Each downstream skill runs its own interaction gates.

16. Interview Log

Full interview log: design/user-flow-personal-workstation-interview.md. Date 2026-06-17, topic personal-workstation, flat mode. Invocation: /user-flow-map redo from scratch.

Evidence Consulted

research/positioning.md — Agent Conductor persona, DIY-stack alternative, "your agents never stop" benefit, mobile-approval differentiator, zero-inbound posture.
research/journey-map.md — onboarding/aha-moment, device-switch continuity, approval routing, diff-review/ship.
research/icp.md — solo-dev / technical-founder profile, 3–8 concurrent sessions, budget authority.
research/concept-brief-gblock-party-personal.md — single-user scope, BYO-client model, infra constraints, tool integration unknowns, non-goals.
research/_working/preliminary-user-flow-map-research.md — prior tool-integration patterns, session-persistence-by-tool, access-mode architecture (Modes A/B/C).
Prior misplaced artifacts in specs/ (archived) used as a reference baseline for the redo.
.agents/project.json — flat-mode single product; product-design pack enabled.

Redo Rationale & Location Correction

The prior flow map and interview log were written to specs/ (specs/user-flow-personal-workstation.md, -interview.md) and a stray copy at the repo root. This skill forbids writing pre-prototype flow maps to specs/ — design/ is the canonical home.
"Redo from scratch" was executed as a clean rebuild into design/ (flat mode), with a new flow-tree manifest. No design/ directory or manifest previously existed.
Misplaced copies archived to docs/history/archive/2026-06-17/104712/ before removal; existing alignment page archived to the same path before regeneration.

Flow Assumptions Checkpoint (presented inline)

Covered persona/role/goal, entry points & triggers, happy path, alternate paths, key decisions, ~10-screen inventory, states, failure/recovery, handoffs, and boundaries/non-goals. Each assumption tagged with provenance.

User response: "looks good to me" — confirmed as presented. Also confirmed running in one continuous pass (no chunked mode) rather than the per-section setup/brief sessions.

Flow Coverage Checkpoint (presented inline)

Presented an 11-row coverage table (persona/goal, entry points, happy path, branches/decisions, screen inventory, actions per screen, required states, failure/recovery, handoffs, wireframe notes, layout non-goals preserved) plus tree-root framing (7 named branch roots) and carried-forward open questions.

User response (correction, not objection): Claude Code ToS has been updated — subscriptions are now usable from third-party applications per a recent Anthropic announcement / email blast.

Questions Asked, Options, Recommendations & Responses

#	Topic	Options / Recommendation	User Response
Q1	Run mode	One continuous pass (recommended — full research already in context) vs. chunked per-section sessions	One continuous pass
Q2	Assumptions checkpoint	Confirm / correct / flag	"looks good to me" — confirmed as-is
Q3	Coverage — anything missing?	Confirm coverage or flag missing branch/state/handoff	Flagged one correction: Claude Code ToS now permits third-party-app subscription use

Corrections Carried Into Deliverables

Claude Code ToS — resolved. Removed "pending ToS review" deferral and the ToS-compliance open question. Claude Code CLI + Claude Agent SDK are now first-class supported BYO-client tools with no asterisk. Architecture framing ("your VM, your subscription, router-not-proxy") preserved. Recorded as durable project memory (claude-code-tos-third-party).
Output location corrected from specs/ to design/ per skill convention.

Coverage Result & Remaining Gaps

All checkpoint dimensions covered. Remaining gaps are tracked as Open Questions in the flow map (not resolved here): xterm.js latency budget (Mode B viability); Multica stdout-parsing generality across tools; push-notification reliability on iOS Safari; code-server (Mode C) MVP ROI; agent resource isolation at 5–12 concurrent sessions; BYO-client connectivity validation (load-bearing).

17. Alignment Gates

Gates 1–6 are placed inline under the content they govern (assumptions, flow map, branch/decision coverage, state coverage, failure/handoff coverage, wireframe notes). Gates 7–8 below cover artifact destination/file changes and the downstream route. All gate questions are confirmations of artifacts already written to design/.

Gate 7: Artifact Destination & Proposed File Changes approved

Destination and the file-write set ask the same path-destination question here, so they are combined into one gate per the de-duplication rule. The files have already been written to the paths below; this confirms they are correct.

Confirm the canonical artifacts at these paths:

design/user-flow-personal-workstation.md (flow map)
design/user-flow-personal-workstation-interview.md (interview log)
design/flow-tree-personal-workstation.yaml (flow-tree manifest)
alignment/user-flow-map-personal-workstation.html (this review page)

Decision: Approved — paths and file set correct as written

Gate 8: Downstream Handoff Choice approved

After approval, how should the agent proceed toward /ux-variations? Continuing immediately still requires the next skill's own interaction gates — this choice does not skip them.

What is the downstream handoff?

Decision: Stop here / clear context — I will start /ux-variations [branch] in a fresh session later