fix(goal): immediate goal.updated feedback + mode-aware start button (#59)

Goal Loop control changes updated in-memory state but emitted no
immediate goal.updated event, so the client status bar never reflected
them until the next tick (a full subagent turn). stop() was worst: it
cancels the driver job, so no further tick ever fires and the UI stayed
stuck on "running" forever.

- goal-manager: extract publishGoalEvent + publishControlPhase; cache
the live ledger/stall/gaps on GoalControl (updated each tick) so control
transitions publish the real budget, not zeros.
- start/pause/resume/stop now emit an immediate goal.updated.
- finalizeOutcome guards the driver's terminal tap on a live control so
a cancelled driver's late "needs_human" outcome cannot clobber the
user's explicit "stopped".

The "convert plan -> goal" button gated on session_plan, which only the
plan tool populates — but loop/design modes author the plan as the repo
file goal+plan.md, so the button never appeared in the modes it belongs
to and did appear in auto (redundant/confusing).

- New GoalManager.startable() mirrors start()'s plan precedence
(session_plan -> goal+plan.md -> none) without side effects, flag-gated.
- New GET /deepagent/goal/startable route + handler.
- Button now gates on capability x mode in {loop,design} x startable,
and shows a success toast on start. i18n goal.start.success (en/zh/zht).

### Issue for this PR

Closes #

### Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Refactor / code improvement
- [ ] Documentation

### What does this PR do?

Please provide a description of the issue, the changes you made to fix
it, and why they work. It is expected that you understand why your
changes work and if you do not understand why at least say as much so a
maintainer knows how much to value the PR.

**If you paste a large clearly AI generated description here your PR may
be IGNORED or CLOSED!**

### How did you verify your code works?

### Screenshots / recordings

_If this is a UI change, please include a screenshot or recording._

### Checklist

- [ ] I have tested my changes locally
- [ ] I have not included unrelated changes in this PR

_If you do not follow this template your PR will be automatically
rejected._

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: deepagent-ai

packages/app/src/components/deepagent/goal-start-button.tsx

@@ -3,9 +3,17 @@ import { Button } from "@deepagent-code/ui/button"
 import { Icon } from "@deepagent-code/ui/icon"
 import { useServerSync } from "@/context/server-sync"
 import { useSDK } from "@/context/sdk"
+import { useLocal } from "@/context/local"
 import { useLanguage } from "@/context/language"
 import { showToast } from "@/utils/toast"
-import { fetchCapabilities, startGoal, type PanelGoalClient } from "./panel-goal.api"
+import { fetchCapabilities, fetchGoalStartable, startGoal, type PanelGoalClient } from "./panel-goal.api"
+
+// The collaboration modes where "convert plan → supervised goal" makes sense. loop/design are BOTH
+// powered by the Goal Loop engine and are designed to have the human START the loop after the plan is
+// authored (loop: agent writes goal+plan.md; design: user writes it). auto is autonomous end-to-end in
+// the current turn — a supervised background goal would be a confusing, redundant second door there, so
+// the button must NOT appear in auto. plan is hidden and never the client-visible current mode.
+const GOAL_MODES = new Set(["loop", "design"])
 
 /**
  * V3.9 §D — "convert plan → goal" starter.
@@ -34,6 +42,7 @@ function errorMessage(err: unknown): string {
 export function GoalStartButton(props: { sessionID: string }) {
   const sdk = useSDK()
   const serverSync = useServerSync()
+  const local = useLocal()
   const language = useLanguage()
   const [busy, setBusy] = createSignal(false)
 
@@ -45,14 +54,31 @@ export function GoalStartButton(props: { sessionID: string }) {
   )
   const goalAvailable = createMemo(() => capabilities()?.goalLoop === true)
 
-  const plan = createMemo(() => (props.sessionID ? serverSync.data.session_plan[props.sessionID] : undefined))
-  const hasPlan = createMemo(() => (plan()?.steps.length ?? 0) > 0)
+  // The current collaboration mode (auto/loop/design) — the button only applies to loop/design. Sourced
+  // from local.agent.current() (session-scoped mode selection), the same source the mode selector uses.
+  const currentMode = createMemo(() => local.agent.current()?.name)
+  const modeAllows = createMemo(() => GOAL_MODES.has(currentMode() ?? ""))
 
-  // A goal is "live" for this session iff the persistent session_goal pointer exists and is not in a
-  // terminal phase the user has dismissed — while present, GoalStatusBar owns the surface.
+  // A goal is "live" for this session iff the persistent session_goal pointer exists — while present,
+  // GoalStatusBar owns the surface. Checked FIRST so we don't probe startability for an already-running
+  // goal.
   const activeGoal = createMemo(() => (props.sessionID ? serverSync.data.session_goal[props.sessionID] : undefined))
 
-  const show = createMemo(() => goalAvailable() && hasPlan() && !activeGoal())
+  // Whether a plan actually exists to start, resolved server-side (session_plan OR repo goal+plan.md).
+  // Re-fetched when the session, mode-eligibility, active-goal, or the in-session plan changes — the last
+  // dependency makes the button appear promptly after the agent writes a plan mid-conversation. Only
+  // probed when the mode allows and no goal is live, to avoid needless requests.
+  const [startable] = createResource(
+    () =>
+      props.sessionID && goalAvailable() && modeAllows() && !activeGoal()
+        ? ([props.sessionID, serverSync.data.session_plan[props.sessionID]?.steps.length ?? 0] as const)
+        : undefined,
+    ([sessionID]) => fetchGoalStartable(client(), sessionID),
+  )
+
+  const show = createMemo(
+    () => goalAvailable() && modeAllows() && !activeGoal() && startable()?.startable === true,
+  )
 
   const onStart = async () => {
     if (busy() || !props.sessionID) return
@@ -61,8 +87,11 @@ export function GoalStartButton(props: { sessionID: string }) {
       const snapshot = await startGoal(client(), { sessionID: props.sessionID })
       if (!snapshot) {
         showToast({ title: language.t("goal.start.failed") })
+      } else {
+        // The server emits an immediate goal.updated (phase=running) on start, so GoalStatusBar takes
+        // over this surface right away. This toast is the belt-and-suspenders confirmation for the click.
+        showToast({ title: language.t("goal.start.success"), variant: "success" })
       }
-      // On success the goal.updated event drives GoalStatusBar to appear; nothing to do here.
     } catch (err) {
       showToast({ title: language.t("goal.start.failed"), description: errorMessage(err) })
     } finally {

packages/app/src/components/deepagent/panel-goal.api.ts

@@ -175,3 +175,26 @@ export const goalStatus = async (
   })
   return response.data?.goal ?? null
 }
+
+export type GoalStartable = { startable: boolean; source: "plan" | "file" | "none" }
+
+/**
+ * Whether a goal can be started for this session right now, resolved SERVER-SIDE with the same plan
+ * precedence start() uses (session_plan → repo goal+plan.md → none). The button gates on this instead
+ * of reading session_plan directly, because loop/design modes author the plan as the repo file (never
+ * touching session_plan), so a client-only hasPlan() check would hide the button in exactly the modes
+ * where it belongs. Tolerant of an older server that lacks the route (treated as not-startable).
+ */
+export const fetchGoalStartable = async (
+  client: PanelGoalClient,
+  sessionID: string,
+): Promise<GoalStartable> => {
+  const response = await client.client.request<GoalStartable>({
+    method: "GET",
+    url: `/deepagent/goal/startable?sessionID=${encodeURIComponent(sessionID)}`,
+  })
+  return {
+    startable: response.data?.startable ?? false,
+    source: response.data?.source ?? "none",
+  }
+}

packages/app/src/i18n/en.ts

@@ -932,6 +932,7 @@ export const dict = {
   "sidebar.wiki": "Repo & Wiki",
   "goal.start.hint": "Plan ready — run it as a supervised goal",
   "goal.start.button": "Run as goal",
+  "goal.start.success": "Goal started — running in the background",
   "goal.start.failed": "Couldn't start the goal",
   "wiki.title": "Repo & Wiki",
   "wiki.description": "Read, search, and govern the four graphs. Knowledge and Memory are editable; Documents and Code are read-only.",

packages/app/src/i18n/zh.ts

@@ -793,6 +793,7 @@ export const dict = {
   "sidebar.wiki": "仓库与百科",
   "goal.start.hint": "计划已就绪 — 转为受监督的长跑目标",
   "goal.start.button": "转为 Goal",
+  "goal.start.success": "目标已启动，正在后台运行",
   "goal.start.failed": "无法启动目标",
   "wiki.title": "仓库与百科",
   "wiki.description": "阅读、检索、治理四张图。知识与记忆可编辑；文档与代码只读。",

packages/app/src/i18n/zht.ts

@@ -646,6 +646,7 @@ export const dict = {
   "review.scope.global": "全域",
   "goal.start.hint": "計劃已就緒 — 轉為受監督的長跑目標",
   "goal.start.button": "轉為 Goal",
+  "goal.start.success": "目標已啟動，正在背景執行",
   "goal.start.failed": "無法啟動目標",
   "wiki.title": "倉庫與百科",
   "wiki.description": "閱讀、檢索、治理四張圖。知識與記憶可編輯；文件與程式碼唯讀。",

packages/deepagent-code/src/server/routes/instance/httpapi/groups/deepagent.ts

@@ -322,6 +322,10 @@ export const DeepAgentGoalSnapshot = Schema.Struct({
 })
 export const DeepAgentGoalStatusResult = Schema.Struct({ goal: Schema.NullOr(DeepAgentGoalSnapshot) })
 export const DeepAgentGoalMutateResult = Schema.Struct({ ok: Schema.Boolean })
+export const DeepAgentGoalStartableResult = Schema.Struct({
+  startable: Schema.Boolean,
+  source: Schema.Literals(["plan", "file", "none"]),
+})
 
 // ── V3.9 §B Repo & Wiki ────────────────────────────────────────────────────
 // The human-facing projection of the four graphs. Read-only browse + governed knowledge edit +
@@ -650,6 +654,13 @@ export const DeepAgentApi = HttpApi.make("deepagent").add(
         error: DeepAgentPromotionError,
       }),
     )
+    .add(
+      HttpApiEndpoint.get("goalStartable", `${root}/goal/startable`, {
+        query: Schema.Struct({ ...WorkspaceRoutingQueryFields, sessionID: Schema.String }),
+        success: described(DeepAgentGoalStartableResult, "Whether a goal can be started + plan source"),
+        error: DeepAgentPromotionError,
+      }),
+    )
     .add(
       HttpApiEndpoint.get("wikiPages", `${root}/wiki/pages`, {
         query: Schema.Struct({ ...WorkspaceRoutingQueryFields, type: Schema.optional(Schema.String) }),

packages/deepagent-code/src/server/routes/instance/httpapi/handlers/deepagent.ts

@@ -559,6 +559,9 @@ export const deepagentHandlers = HttpApiBuilder.group(InstanceHttpApi, "deepagen
     const goalStatus = Effect.fn("DeepAgentHttpApi.goalStatus")(function* (ctx) {
       return { goal: yield* goals.status(ctx.query.sessionID) }
     })
+    const goalStartable = Effect.fn("DeepAgentHttpApi.goalStartable")(function* (ctx) {
+      return yield* goals.startable(ctx.query.sessionID)
+    })
 
     // ── V3.9 §B Repo & Wiki ─────────────────────────────────────────────────
     // Read-only projection + governed knowledge edit + full-text search. All fail-closed on the wiki
@@ -679,6 +682,7 @@ export const deepagentHandlers = HttpApiBuilder.group(InstanceHttpApi, "deepagen
       .handle("goalResume", goalResume)
       .handle("goalStop", goalStop)
       .handle("goalStatus", goalStatus)
+      .handle("goalStartable", goalStartable)
       .handle("wikiPages", wikiPages)
       .handle("wikiPage", wikiPage)
       .handle("wikiSearch", wikiSearch)