ForkTTY 0.2.0-alpha.18

[0.2.0-alpha.18] - 2026-07-06

Added

• Team workers can now persist a bounded final report through
  team.worker.upsert, CLI, and MCP; the report is returned by team.get,
  counted in team.summary, and surfaced in team.worker.health.
• task.strategy.plan and task.strategy.apply responses now include
  planner_version so agents can record which ForkTTY planner produced or
  applied a routing decision.
• Task strategy apply now bootstraps an initial planned workflow loop record
  for plans with layers.loop_metadata: true and context snapshots warn with
  loop_never_recorded when such workflows are finished without loop
  adoption evidence. The bootstrap now includes pending verifier-contract gates
  so loops start with explicit review/implementation/verification checks.
• Task strategy apply now appends an advisory next-best-harness hint to
  assignment launchability and worker launch failures, naming the highest
  scored other ready harness for the same role so callers can retry without
  re-planning; apply never retries or substitutes harnesses on its own.
• Task strategy harness_signals now accept an optional cooldown_kind
  (quota, auth, crash, or timeout) so the soft cooldown penalty scales
  with the cause instead of weighing every reason the same; unknown kinds and
  kinds without cooldown: true are rejected.
• Task strategy planning now infers an advisory soft cooldown for a harness
  from ForkTTY's own workflow history (at least two recent failed
  task-strategy workflows naming that harness, cleared by a newer success),
  named in plan reasons and score factors; explicit harness_signals still
  replace inference for the harnesses they name.
• Added dry-run-first orchestration.cleanup over socket, MCP
  orchestration_cleanup, and forktty cleanup orchestration so stale
  team/workflow records can be inspected and conservatively closed without
  touching live worker surfaces.
• Added ergonomic workflow-loop CLI wrappers: workflow-loop-gate to merge one
  gate update, workflow-loop-step-done to mark a stage complete, and
  workflow-loop-publish to record a published commit stop reason without
  hand-writing the full gates array.
• Added workflow-loop-iteration-start and workflow-loop-iteration-done
  wrappers so agents can advance bounded loop passes and record the pass result
  without hand-writing workflow.loop.set payloads.
• Added read-only forktty worktree-doctor diagnostics that report repository
  and linked-worktree health without creating, pruning, merging, or removing
  any worktree state.
• Added a short GETTING_STARTED.md walkthrough and docs/socket-api.md
  stability map so users and agents can distinguish stable-for-alpha socket
  calls from public alpha orchestration surfaces.
• Added METRICS.md with manual attention-first UI quality targets for the
  Router rail and workflow feed.
• Added an Attention-first UI smoke checklist to release QA so those metrics
  are exercised before alpha releases instead of remaining advisory only.
• Extended METRICS.md and release QA with general anti-slop UI quality checks
  tied to the existing GTK visual rules.

Changed

• Softened the orange status dots so they read as quiet ambient cues: warn
  .rail-dots (sidebar nav, worker/health, feed, pane footers) and the
  .pane-attention-dot now render at reduced opacity instead of full-strength
  orange.
• Quietened neutral status indicators so only meaningful state carries colour:
  the workflow-feed "live" marker is now a small green dot plus a muted label
  instead of a filled green pill, and the Router status chip's idle/neutral
  state is plain muted text (transparent background/border) rather than a filled
  grey box — active ok/warn/err states keep their subtle tinted pill.
• Consolidated the orchestration status-signal palette (rail dots, rail-strip
  badges, status chips, list rows, feed status) onto the shared semantic colour
  tokens: warn and error indicators now render the same warm-orange
  (@ft_warning) and danger red (@ft_danger) used elsewhere instead of two
  divergent gold/red hues, and the status blue is now the named @ft_info
  token — one hue per meaning across the whole app.
• Agent-status badges in the sidebar (.workspace-status-badge) and pane
  headers (.pane-agent-badge) are now compact squared pills (5px radius,
  tighter padding, hairline border) instead of fully rounded chips: live/running
  reads sober green, needs-input/attention warm orange, idle/exited neutral
  grey.
• Normalized corner radii to a tight 3-step scale (4px small controls, 6px
  buttons/badges, 8px cards/rows/dialogs, plus full-round pills), collapsing the
  previous ad-hoc mix of 4/5/6/7/8px so nested surfaces read as one system.
• Aligned the workflow-feed / router status chips (live / idle / warn) to the
  token system: 6px radius, neutral surface + hairline tokens, and the warm
  accent for the warning state.
• Refined the header count badges (notification/agent) to a compact squared
  chip on the sober warm accent, replacing the red/orange full-round dots.
• Unified surface borders onto a single hairline color and evened out
  horizontal-padding drift, so cards, rows, and dialogs share one border weight
  and spacing rhythm instead of three near-identical grays.
• Unified the "needs attention / needs input" accent across the app onto the
  warm-orange ForkTTY accent (#e88745/#eaa06a), replacing the inconsistent
  gold and peach tints previously used by the header attention button, sidebar
  needs-attention rail, needs-attention pane border/dot, inline warning status,
  and agent/notification prompt states. The distinct "current" row marker and
  keyboard focus rings are unchanged.
• The GTK workbench now follows the agent-workspace layout end to end: the
  titlebar carries a Router cluster (breadcrumb, workspace selector, Plan and
  Review Plan shortcuts into the read-only Router planner) plus live team
  chips; the sidebar gains TEAM, RESOURCES, and Settings/About sections; the
  right-side rail shows an attention-first summary plus structured
  strategy/loop/approval/worker/report/notification rows with working
  Review/Deny on pending Feed approvals and a notifications Clear-all; the
  workflow feed gets wall-clock timestamps, per-kind status colors, filter
  tabs, and a Clear button; split panes gain a slim footer with the shell name
  and agent lifecycle; and the status bar summarizes the active Router strategy
  and loop.
• The workflow feed now includes an ATTENTION tab that isolates approvals,
  errors, warnings, stale/conflict signals, and needs-input rows from routine
  workflow/log churn.
• The sidebar Resources section now exposes only the implemented Worktrees
  shortcut instead of placeholder Knowledge Base, Snippets, Environments, and
  Secrets rows.
• The Router rail and bottom workflow feed can now be collapsed from their
  headers for temporary workspace space recovery while the Settings toggles
  remain the persistent show/hide controls.
• Reworked both collapsed states: the collapsed Router rail is a slim strip
  with an expand chevron plus pending-approval and unread-notification badges
  (and now stays collapsed even after the divider has been dragged), the rail
  header no longer scrolls away with the rail body, the workflow feed
  collapses with a slide animation and re-expands when a feed tab is clicked,
  collapse controls use chevron icons instead of ASCII arrows, and the rail
  status and feed "live" pills were restyled (status pill now colored by
  state instead of always green).
• Settings follows the same agent-workspace pass: Interface gains live "Show
  orchestration rail" and "Show workflow feed" toggles (new
  appearance.show_orchestration_rail / appearance.show_workflow_feed
  config keys, default on), Worktrees links the worktree manager, Agents can
  re-scan provider readiness on demand, Notifications can clear the in-app
  history, and Privacy states the local-first guarantees and stored data
  locations next to the telemetry toggle.
• team.finish now accepts compact/--compact to finalize teams without
  echoing the full team record and mailbox bodies in the response.
• Team worker health now distinguishes workers that have no heartbeat plumbing
  from stale workers and uses persisted agent-session lifecycle evidence to
  report idle, needs_input, or done when hooks already recorded it.
• The agent skill and operating guide now make verify-loop state recording
  part of the strategy contract: when an applied task-strategy plan sets
  layers.loop_metadata: true, apply seeds the initial planned loop record,
  and agents must update stage/iteration/gates each pass and record the stop
  reason at the end so loop_summaries can restore loop position after
  context compaction.
• Reduced the always-sent ForkTTY MCP initialize instructions and task-strategy
  tool descriptions so agents get the routing essentials without duplicating
  the full operating guide; the complete guide remains available through the
  MCP resource and prompt.
• forktty skills setup and forktty skills remove now retain only the three
  newest ForkTTY-managed skill backups per target and report pruned backups,
  while leaving unmanaged .bak-* directories untouched.
• Task strategy planning now accepts normalized task_kind / task_class_hint
  aliases such as bugfix, feature, review, and research, so agents can
  pass clear user intent across languages without relying on ForkTTY keyword
  guessing or exact internal enum names.
• Task strategy planning now treats explicit iterative goals such as repeat
  verification, iterative audits, and "keep checking until clean" as
  verify-loop work, and preserves review_only strategy for explicit review
  hints while still setting layers.loop_metadata: true; no hidden scheduler
  is started.
• The Router rail loop row now shows stage plus iteration budget and compact
  passed/failed/running gate counts when loop metadata exists.
• Context snapshots now warn with loop_passed_without_evidence when a
  terminal workflow records a successful loop stop reason without workflow
  evidence, keeping verifier results auditable after compaction.

Fixed

• Fixed the Router rail and workflow feed so global task-strategy workflow and
  team records created without an explicit workspace target remain visible in
  the active workspace instead of disappearing behind the workspace filter.
• Fixed hook-driven agent status targeting so untargeted hook events with a
  unique hook_session_cwd bind to the matching live surface, while ambiguous
  cwd matches are rejected instead of showing false Working/needs input
  state on the active workspace; status session binding is now pinned for
  Codex, Claude, Grok, Pi, Antigravity, and OpenCode aliases.
• Fixed notification clearing so closing a desktop notification is best-effort
  and cannot block the socket response used by forktty hooks test.
• Fixed Router rail and Settings notification clearing so OSC 99 close reports
  are sent off the GTK callback path, preventing terminal close-report
  handshakes from freezing Clear actions.
• Fixed persisted hook prompt approvals so feed.list, context.snapshot,
  and UI pending-approval badges mark them stale after the originating live
  notification is gone instead of continuing to report a pending approval after
  restart.
• Sanitized forktty worktree-doctor text output so repository paths and Git
  worktree metadata containing terminal control characters cannot emit raw
  ANSI/OSC sequences.
• Fixed Codex MCP setup so managed ForkTTY MCP servers inherit
  XDG_RUNTIME_DIR, allowing sessions without FORKTTY_SOCKET_PATH to find
  the default $XDG_RUNTIME_DIR/forktty.sock instead of falling back to the
  legacy /tmp socket path.
• Fixed top-level CLI routing for the ergonomic workflow-loop wrappers so
  forktty workflow-loop-gate, workflow-loop-step-done, and
  workflow-loop-publish reach the socket CLI instead of failing as unknown
  arguments.
• Fixed task strategy worktree isolation so a caller-controlled review flag on
  a parallel_research plan cannot suppress dirty-repository isolation for a
  mutating goal; only coherent review_only plans retain the read-only
  exemption.
• Fixed task strategy goal keyword false positives: artifact words such as
  "quickstart" or "smaller" no longer trigger the fast profile, "parallelize
  ..." editing goals no longer route to parallel research lanes, and refactor
  goals now classify as feature implementation instead of repo inspection; a
  goal-routing corpus test pins classifier, profile, and strategy behavior.
• Fixed task strategy harness routing signal and registry JSON to tolerate
  missing optional fields (cooldown, locked_out, harnesses) instead of
  failing deserialization; absent signals now mean "no signal".
• Fixed more task strategy classifier false positives found by a multi-harness
  review: inspection-first goals that mention tests ("Explain how the tests
  are organized"), documentation nouns matching the old "verif" prefix
  ("Document how verification works in CI"), and adjectival "built" ("Inspect
  the built artifacts directory") no longer classify as editing work, and the
  researcher assignment capacity factor no longer claims a capacity benefit
  when it awards zero points.
• Fixed Settings dialog live behavior so Reset also cleans previously enabled
  detached PTY persistence sessions, enabling GitHub PR lookup triggers an
  immediate refresh instead of waiting for the next timer tick, and agent setup
  buttons cannot be clicked while their initial status check is still pending.
• Fixed small GTK polish issues in window controls, workspace switching,
  worktree dialogs, welcome/settings copy, and terminal search icons so labels,
  tooltips, and bundled icons stay consistent across the app.
• Fixed Antigravity PreToolUse hook responses so ForkTTY returns the current
  {"decision":"allow"} gating decision instead of the older approve value
  that agy 1.0.16 rejects before tool execution.
• Fixed notification attention tracking so reading, dismissing, or clearing
  notifications no longer clears a pane's unrelated unread-output badge; the
  notification panel also refreshes header state immediately and no longer
  renders freshly-read rows as unread.
• Fixed notification clearing so the persisted Feed marks cleared
  notification rows read while still keeping them in history, preventing the
  new Router rail and workflow feed from showing cleared notifications as
  still unread.
• Fixed the Router rail notification Clear-all action so it only clears the
  notifications visible in the active workspace instead of deleting hidden
  notifications from other workspaces.
• Fixed the Router rail notification Clear-all action so it also closes
  matching desktop notifications and sends OSC 99 close reports for terminal
  notifications that requested close reporting.
• Fixed the Settings notification-history Clear action so it also closes
  matching desktop notifications and sends OSC 99 close reports for terminal
  notifications that requested close reporting.
• Fixed the new Router rail and workflow feed live state so worker health uses
  live pane lifecycle such as needs_input instead of raw persisted worker
  status, and the workflow feed LOGS tab shows metadata logs instead of
  notification rows.
• Fixed Router rail worker health so a live agent session is applied only when
  its provider matches the team worker, preventing a recycled surface with a
  different agent session from making another worker look blocked.
• Fixed hook metadata binding so a status event from one provider cannot steal
  a live surface already bound to a different provider session, preventing Grok
  panes from appearing as Claude in agent status surfaces.
• Fixed Claude hook PermissionRequest handling so sessions running in
  bypassPermissions mode refresh the permission-mode status without creating
  a stale human-attention prompt notification.
• Fixed Claude hook Notification handling so informational notifications such
  as auth success or background-task completion do not briefly mark an actively
  running session as needs_input.
• Fixed provider hook PermissionRequest handling so skip-permissions modes do
  not create stale permission-required prompt notifications, while still
  surfacing the bypass mode as a red status signal.
• Fixed compact context snapshots so finalized Feed approvals (approved,
  denied, or dismissed) are omitted from the operational feed while
  pending/stale attention items and full include_feed_trace history remain
  available.
• Fixed the Router rail notification "Clear all" action so it actually clears
  in-app notification rows instead of only marking them read and leaving them
  visible.
• Fixed the Router rail, header chips, status summary, and workflow feed so
  they scope workflow/team state to the active workspace instead of continuing
  to show the most recently updated router task after its workspace was closed.
• Fixed orchestration UI state after restarts so closed or prior-session
  workspace/surface ids referenced by durable workflow/team records are
  reserved before new GTK workspaces are created, preventing old router/team
  records from being adopted by an unrelated fresh workspace.
• Fixed orchestration UI restart state so pending Feed approvals also reserve
  their referenced workspace/surface ids before fresh GTK workspaces are
  created, preventing stale approval prompts from reattaching to unrelated
  panes after restart.
• Fixed task-router loop intent inference so non-English loop phrases no
  longer bypass the structured task_kind / router_profile hint contract.
• Fixed task-router loop intent inference so broad phrases such as "with loop"
  or "until clean" no longer seed loop metadata unless the goal also names a
  repeat or verification action.
• Fixed split-pane footer shell labels so they use ForkTTY's configured shell
  instead of the parent process SHELL environment variable.
• Fixed the Router rail so capped Worker Health and Worker Reports sections
  show a +N more overflow caption instead of silently hiding extra rows.
• Fixed the workflow feed combined view so bursts of metadata logs, especially
  Antigravity tool logs, cannot push workflow, team, approval, or notification
  rows out of the visible five-line summary.
• Fixed the workflow feed so notification rows are scoped to the active
  workspace and live surfaces, and the LOGS tab uses its full five-row budget
  instead of inheriting the mixed feed's compact log cap.
• Fixed workflow feed empty states so the EVENTS and LOGS tabs describe
  their own missing content instead of always saying there are no workflow
  events.
• Fixed the workflow feed Clear action so clearing one tab only hides rows in
  that tab instead of also hiding older rows from the other feed filters.
• Fixed the workflow feed Clear action so clearing a tab in one workspace no
  longer hides older feed rows after switching to another workspace.
• Fixed Settings privacy copy so it no longer claims "No analytics" next to
  the configurable anonymous daily ping toggle.
• Fixed the Router rail so active workflow/team records stay selected over
  newer terminal records in the same workspace, preventing old completed runs
  from hiding current worker health or loop state after cleanup/evidence churn.
• Fixed the Router rail worker reports and approvals so five-worker review
  teams show all five report/health rows, pending approvals whose target
  surface has closed are hidden from the rail, and prompt notifications whose
  target surface has already been closed stay hidden.
• Fixed Feed approval responses so pending approvals whose workspace or surface
  target went stale are persisted as stale and rejected instead of being
  approved through the socket after feed.list already showed them stale.
• Fixed orchestration.cleanup so team workers whose surface remains in the
  workspace model but no longer has a terminal runtime are treated as stale
  instead of blocking cleanup as manual-review live workers.
• Fixed context.snapshot workflow summaries/details so active non-loop
  workflows bound to missing surfaces report surface_present,
  stale_binding, and a workflow consistency warning.
• Fixed surface.focus over the socket/MCP boundary so focusing a surface in
  an inactive workspace also selects that workspace and rolls back to the
  previous workspace if terminal startup fails.
• Fixed MCP task_strategy_apply ambient targeting so fallback
  FORKTTY_SURFACE_ID overrides the ambient workspace target like the socket
  CLI, avoiding accidental over-constrained workspace/surface pairs.
• Fixed restored multi-tab panes so the workspace focused surface is also made
  the active tab in its leaf, preventing hidden-tab focus after loading or
  repairing a session.
• Fixed tab selection from shortcuts, the command palette, and pane tab strips
  so it saves session state immediately; tab-strip items are now keyboard
  activatable and their context menu shows the existing shortcut hints.
• Fixed the vendored Ghostty GTK embedding source so it carries ForkTTY's
  resize cursor-preservation and bounded wrap-count patches, preventing the
  packaged ghostty-gtk-embed.so path from missing the same maximize/resize
  safety fixes already applied to the libghostty-vt build path.
• Fixed the Ghostty GTK packaging probe so deb/AppImage builds require
  ghostty_gtk_surface_send_text and ghostty_gtk_text_free, avoiding
  verified packages with panes that render but are not socket-ready or cannot
  return captured text.
• Fixed MCP/README/SPEC wording for embedded Ghostty terminal capture so
  surface_capture_tail and persistent_scrollback_lines no longer promise an
  off-screen scrollback tail when the current GTK embedding ABI only provides
  visible-tail polling for that path.
• Fixed task strategy classification so parallelism requests over an editing
  goal (bugfix or implementation wording) route to parallel_experiment
  instead of read-only parallel_research.
• Fixed task strategy plan/apply input validation so oversized goals are
  rejected before they can be copied into workflow/team state or worker
  prompts.
• Fixed task strategy planning input validation so oversized routing reason
  hints are rejected before they can inflate plan score explanations.
• Fixed inferred task strategy cooldown reasons so long workflow IDs cannot
  make planner-generated score factors or plan reasons fail apply-time size
  validation.
• Fixed task strategy error reporting so unsupported routing enum values and
  malformed submitted plans cannot echo oversized caller-controlled strings.
• Fixed task strategy text validation so goals reject terminal control
  characters other than newline or tab, and routing reason hints reject control
  characters before reaching worker prompts or score explanations.
• Fixed task strategy text validation so terminal/control characters at trimmed
  string edges are rejected instead of silently dropped.
• Fixed task strategy last-known-good inference so invalid harness ids in old
  workflow plan text are ignored instead of inflating router explanations.
• Fixed task strategy apply so submitted plan reasons and score details are
  revalidated before they can inflate workflow/team state, approval
  fingerprints, or worker prompts.
• Fixed task strategy apply so client-submitted explanation arrays and score
  factor lists, and approval lists are count-bounded before mutation, avoiding
  token-heavy approval fingerprints from oversized but individually valid plan
  details.
• Fixed task strategy apply so duplicate approval entries in a submitted plan
  are rejected before mutation instead of inflating approval fingerprints with
  redundant state.
• Fixed task strategy apply so team strategies reject client-submitted role
  mixes the planner would never produce, such as implementer-plus-reviewer
  plans with duplicate reviewers and no implementer.
• Fixed task strategy apply so team strategies cannot be staged without a team
  layer, avoiding workflow-only runs for plans that require visible worker
  tasks.
• Fixed task strategy apply so tracked strategies cannot be staged without a
  workflow layer, avoiding no-op runs with no durable workflow or team
  monitoring target.
• Fixed task strategy apply so submitted plans with more assignments than
  visible team worker capacity are rejected before creating partial
  workflow/team state.
• Fixed task strategy apply so submitted plans with no assignments are rejected
  before creating empty workflow plans or loop metadata.
• Fixed task strategy apply so client-submitted plans cannot force team state
  onto strategies that do not support team orchestration.
• Fixed task strategy apply so submitted team or loop metadata layers require
  workflow state instead of creating orphan team records or no-op loop runs.
• Fixed task strategy apply so client-submitted plans cannot force loop
  metadata onto strategies that do not support verify-loop orchestration.
• Fixed task strategy apply so client-submitted plans cannot attach assignment
  roles that the selected strategy would not produce, such as eager synthesizer
  workers for parallel research runs.
• Fixed task strategy apply so client-submitted plans cannot inflate assignment
  counts beyond the selected strategy shape, preventing orphan solo/review steps
  and over-wide parallel research runs.
• Fixed team worker recovery so a worker that resumes with an active status
  after team.worker.shutdown clears stale shutdown metadata, and health
  reports persisted shutdown_requested workers consistently even when older
  state lacks the shutdown timestamp.
• Fixed team.worker.launch so teams with a stale recorded leader surface can
  still launch workers from their valid workspace focus instead of failing with
  not_found.
• Fixed orchestration.cleanup so dry_run=false without apply=true is
  rejected instead of mutating stale orchestration records.
• Fixed orchestration.cleanup so non-terminal workers without a recorded
  surface are reported for manual review instead of being closed as stale.
• Fixed task strategy parallel worker prompts so repeated researcher lanes get
  deterministic, distinct scopes instead of duplicate broad instructions.
• Fixed task strategy dirty-repo isolation so apply-time safety also uses the
  normalized plan task class, not only English goal wording.
• Fixed task strategy dirty-repo isolation so a client-submitted review_only
  strategy cannot bypass worktree approval when the submitted task class or
  assignments are mutating.
• Fixed task strategy dirty-repo isolation so apply-time safety treats mutating
  strategy shapes as edit intent even if a client submits a stale read-only
  task class.
• Fixed the managed ForkTTY orchestration skill text so installed agent skills
  describe the same dirty-repo isolation inputs as the socket/MCP runtime.
• Fixed task strategy goal classification so unrelated words that merely start
  with "fix" or "bug" (such as "fixtures") no longer classify a goal as a
  focused bugfix.
• Fixed GTK/Ghostty team message dispatch so socket send_text/submit calls
  wait for the GTK controller's actual send result before acknowledging
  delivered/submitted messages, instead of succeeding after only queueing the
  command.
• Fixed forktty hooks doctor claude so legacy ForkTTY-managed Claude hook
  entries without an explicit installer tag are still recognized when checking
  the installed launcher.

Security

• Rejected task-strategy cwd values whose canonical path is not valid UTF-8,
  avoiding a panic when launching team workers from a symlink to a non-UTF-8
  repository path.
• Fixed GNU env shell-trampoline detection so environment assignment tokens
  that start with = cannot hide a later sh -c command from project-action
  and team-provider command validation.

Downloads

• AppImage is the primary download for this alpha.
• Debian package is available for Debian 13/Trixie+ and Ubuntu 24.04 LTS+.
• Source is available from the tag: https://github.com/Lucenx9/forktty/tree/v0.2.0-alpha.18
• Source builds should clone with submodules: git clone --recurse-submodules https://github.com/Lucenx9/forktty.git.

SHA256SUMS

3017a91b4f7bec3d61fc90544f444bcf54a98f556b4b67981cf05380a732edaa  forktty-0.2.0-alpha.18-x86_64.AppImage
010a8847a4e360fb4afd03219a9d6adad6b15c3258c79fdb80ce14dbee8e77da  forktty-0.2.0-alpha.18-x86_64.AppImage.zsync
f857e9ef7c87a837103ec60d7d11dcc9379290ed4e1293e8972234c405bcfbd0  forktty_0.2.0.alpha.18_amd64.deb