pi-adx-workflow 1.0.0 → 1.1.0

package/README.md

@@ -1,5 +1,6 @@
 # pi-adx-workflow
 
+[![npm](https://img.shields.io/npm/v/pi-adx-workflow)](https://www.npmjs.com/package/pi-adx-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![pi-coding-agent](https://img.shields.io/badge/pi-coding-agent-%E2%89%A51.5-blueviolet.svg)](https://github.com/earendil-works/pi)
 
@@ -60,27 +61,27 @@ per the pi package conventions).
 
 ## Install
 
-Recommended: install as a [pi package](https://github.com/earendil-works/pi) from git:
+Recommended: install as a [pi package](https://github.com/earendil-works/pi) from npm:
 
 ```sh
-pi install git:github.com/mossaab/pi-adx-workflow
+pi install npm:pi-adx-workflow
 ```
 
 Variants:
 
 ```sh
 # project-local (written to .pi/settings.json, loads after project trust)
-pi install --local git:github.com/mossaab/pi-adx-workflow
+pi install --local npm:pi-adx-workflow
 
-# from npm
-pi install npm:pi-adx-workflow
+# from git (tracks the main branch)
+pi install git:github.com/mossaab/pi-adx-workflow
 ```
 
 Manage the install:
 
 ```sh
 pi list                                    # show configured packages
-pi remove git:github.com/mossaab/pi-adx-workflow
+pi remove npm:pi-adx-workflow
 pi update --extensions                     # reconcile git checkouts / npm specs
 ```
 
@@ -187,9 +188,12 @@ saves it to `.pi/specs/<slug>.md`, exits plan mode, and launches nothing.
 State lives **per pi session** in `.pi/adx-flow/state/<sessionId>.json`
 (criteria, findings, execution state, plan-mode and spec-mode flags) — each session has its
 own plan, and resuming a session restores exactly that session's plan/run.
-A new session starts fresh. On the first per-session load, an in-flight run
-still in the legacy shared `.pi/adx-flow/state.json` (status ≠ done) is
-adopted into the new session's file once, so pre-existing runs keep working.
+**New sessions (`/new`, fork) start 100% clean**: no execution is restored and no
+step auto-executes — an in-flight run left behind by a previous session stays in
+*that* session's own file and comes back only when you re-resume it. When a resumed
+session has no per-session file yet, an in-flight run still in the legacy shared
+`.pi/adx-flow/state.json` (status ≠ done) is adopted into its file once, so
+pre-per-session runs keep working — new sessions never touch the legacy file.
 Flow sub-agents (verifier / code reviewer) write to the *parent's* state file
 (passed via the `ADX_FLOW_STATE` env var) so their `flow_meta` updates land
 in the driving session's store. It survives pi restarts — `session_start`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-adx-workflow",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Declarative plan → build → verify → review workflow for pi-coding-agent, with in-house isolated sub-agents and never-stop auto-continue.",
   "type": "module",
   "license": "MIT",

package/src/executor.ts

@@ -156,6 +156,31 @@ export class AdxExecutor {
     )
   }
 
+  /**
+   * Clear in-memory run state when the pi process switches to a brand-new
+   * session (/new, fork): the previous session's run/workflow/sessionId must
+   * not leak into the new one (builder prompt section, persist() target,
+   * isActive() checks). Called from session_start (reason "new"/"fork")
+   * before any restore; the new session's own state file is (by definition)
+   * empty, so nothing is re-entered.
+   */
+  resetForNewSession(): void {
+    this.run = undefined
+    this.workflow = undefined
+    this.sessionId = undefined
+    this.cwd = undefined
+    this.stepDoneCalled = false
+    this.autoContinueCount = 0
+    this.resumeReentry = false
+    // Template-context caches: clear them too so no cross-session value can
+    // surface before the new session's first persist refreshes them (all
+    // readers are already guarded against undefined).
+    this.lastCtx = undefined
+    this.projectStatsCache = undefined
+    this._lastState = undefined
+    this.deps.updateWidget?.()
+  }
+
   // ------------------------------------------------------------------ launch
   async launch(workflowId: string, ctx: ExtensionContext, rawArgs?: string): Promise<void> {
     this.bindCtx(ctx)

package/src/index.ts

@@ -37,10 +37,10 @@ import {
   getSpecModeTools,
   planModeBashGuard,
 } from './modes.js'
-import { loadState, mutateState, onStateWarning } from './store.js'
+import { loadState, mutateState, onStateWarning, setLegacyAdoption } from './store.js'
 import { composeSpecMarkdown, defaultSpecPath, specPathError, writeSpecFile } from './spec.js'
 import { relative, resolve as resolvePath } from 'node:path'
-import { refreshFlowWidget, clearFlowWidget, setModeBadge } from './widgets.js'
+import { refreshFlowWidget, clearFlowWidget, setModeBadge, type ModeBadgeSpec } from './widgets.js'
 import { createAskUserTool } from './ask-user.js'
 import { loadConfig, type AdxConfig } from './config.js'
 import {
@@ -76,30 +76,41 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
   let config: AdxConfig = {}
   /** Pi session id — keys the per-session adx state file (own plan per session). */
   let sessionId: string | undefined
+  /** Latest pending plan/spec flag persist — launch paths await this chain. */
+  let pendingModePersist: Promise<unknown> = Promise.resolve()
 
-  /** Persist the plan-mode flag into the session's state file (resume-friendly). */
-  function persistPlanMode(on: boolean): void {
+  /**
+   * Persist the plan-mode flag into the session's state file (resume-friendly).
+   * Returns the write promise: launch paths AWAIT it so the executor's next
+   * persist() (load + save) sees planMode=false — a fire-and-forget write
+   * used to lose that race, leaving finished runs with planMode=true.
+   */
+  function persistPlanMode(on: boolean): Promise<void> {
     const c = ctx
-    if (!c) return
+    if (!c) return Promise.resolve()
     const sid = sessionId ?? c.sessionManager.getSessionId()
-    void mutateState(c.cwd, sid, (state) => {
+    const p = mutateState(c.cwd, sid, (state) => {
       state.planMode = on
     }).catch(() => {
       /* best effort — the in-memory flag is authoritative */
     })
+    pendingModePersist = p
+    return p
   }
 
   /** Persist the spec-mode flag (and its pinned spec path) for resume. */
-  function persistSpecMode(on: boolean, path?: string): void {
+  function persistSpecMode(on: boolean, path?: string): Promise<void> {
     const c = ctx
-    if (!c) return
+    if (!c) return Promise.resolve()
     const sid = sessionId ?? c.sessionManager.getSessionId()
-    void mutateState(c.cwd, sid, (state) => {
+    const p = mutateState(c.cwd, sid, (state) => {
       state.specMode = on
       state.specPath = on ? path : undefined
     }).catch(() => {
       /* best effort — the in-memory flag is authoritative */
     })
+    pendingModePersist = p
+    return p
   }
 
   // ------------------------------------------------------------------ flag
@@ -172,9 +183,9 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
         return executor.launch(workflow, c, args)
       },
       withConfigDefaults,
-      exitPlanMode: () => {
+      exitPlanMode: async () => {
         const c = ctx
-        if (c) exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+        if (c) await exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
       },
       specOnly: async () => {
         // "Spec only — stop": export the stored criteria as a spec document
@@ -204,13 +215,13 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
       onWritten: (absPath) => {
         const c = ctx
         specPath = absPath
-        if (specMode) exitSpecMode((m, l) => c?.ui.notify(m, l ?? 'info'))
+        if (specMode) void exitSpecMode((m, l) => c?.ui.notify(m, l ?? 'info'))
       },
     }),
   )
 
   // ------------------------------------------------------------------ mode helpers
-  function showBadge(badge: string | undefined): void {
+  function showBadge(badge: ModeBadgeSpec | undefined): void {
     if (config.showWidget === false) badge = undefined
     if (ctx) setModeBadge(ctx, badge, sessionId)
   }
@@ -218,26 +229,35 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
   function enterPlanMode(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void) {
     if (planMode) return
     // Plan mode and spec mode are mutually exclusive read-only modes.
-    if (specMode) exitSpecMode(() => {})
+    if (specMode) void exitSpecMode(() => {})
     planMode = true
     toolsBeforePlanMode = pi.getActiveTools()
     let tools = activatePlanModeTools(pi.getActiveTools())
     // Auto mode is unattended: no interactive question tool.
     if (autoMode) tools = tools.filter((t) => t !== 'ask_user')
     pi.setActiveTools(tools)
-    persistPlanMode(true)
-    showBadge(autoMode ? 'adx: [AUTO] plan → build → verify → recap' : 'adx: [PLAN] read-only · /adx-approve to exit · /adx-run to start')
+    void persistPlanMode(true)
+    showBadge(
+      autoMode
+        ? { mode: 'auto', detail: 'plan → build → verify → recap' }
+        : { mode: 'plan', detail: 'read-only · /adx-approve to exit · /adx-run to start' },
+    )
     notify('adx: plan mode ON (read-only). Propose acceptance criteria with flow_meta. Exit: /adx-approve or Ctrl+Alt+A.', 'info')
   }
 
-  function exitPlanMode(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void) {
+  async function exitPlanMode(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void): Promise<void> {
     if (!planMode) return
     planMode = false
     pi.setActiveTools(getBuildModeTools(toolsBeforePlanMode ?? pi.getActiveTools()))
     toolsBeforePlanMode = undefined
-    persistPlanMode(false)
+    // Badge + notification run synchronously so a fire-and-forget plan↔spec
+    // switch (enterSpecMode → void exitPlanMode) can't be clobbered by the
+    // pending continuation after the new mode's badge is already set.
     showBadge(undefined)
     notify('adx: plan mode OFF (build mode).', 'info')
+    // Last: the persist must land before any launch persist that follows
+    // (exitReadOnlyModes / flow_plan_done await this function for that).
+    await persistPlanMode(false)
   }
 
   function enterSpecMode(
@@ -246,34 +266,47 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
   ): void {
     if (specMode) return
     // Spec mode and plan mode are mutually exclusive read-only modes.
-    if (planMode) exitPlanMode(() => {})
+    if (planMode) void exitPlanMode(() => {})
     specMode = true
     toolsBeforeSpecMode = pi.getActiveTools()
     pi.setActiveTools(getSpecModeTools(pi.getActiveTools()))
     specPath = pathArg || undefined
-    persistSpecMode(true, specPath)
-    showBadge(`adx: [SPEC] read-only · /adx-approve to exit${specPath ? ` · spec: ${specPath}` : ''}`)
+    void persistSpecMode(true, specPath)
+    showBadge({ mode: 'spec', detail: `read-only · /adx-approve to exit${specPath ? ` · spec: ${specPath}` : ''}` })
     notify(
       'adx: spec mode ON (read-only brainstorm/research). Explore, research, then call spec_write ONCE with the full spec markdown. Exit: /adx-approve or Ctrl+Alt+A.',
       'info',
     )
   }
 
-  function exitSpecMode(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void) {
+  async function exitSpecMode(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void): Promise<void> {
     if (!specMode) return
     specMode = false
     pi.setActiveTools(getBuildModeTools(toolsBeforeSpecMode ?? pi.getActiveTools()))
     toolsBeforeSpecMode = undefined
     specPath = undefined
-    persistSpecMode(false)
+    // Badge + notification run synchronously (same reason as exitPlanMode).
     showBadge(undefined)
     notify('adx: spec mode OFF (build mode).', 'info')
+    await persistSpecMode(false)
   }
 
-  /** Exit whichever read-only mode (plan/spec) is active — used before launching a build. */
-  function exitReadOnlyModes(notify: (msg: string, level?: 'info' | 'warning' | 'error') => void): void {
-    if (specMode) exitSpecMode(notify)
-    if (planMode) exitPlanMode(notify)
+  /**
+   * Exit whichever read-only mode (plan/spec) is active — used before
+   * launching a build. Awaited: the flag persists must land BEFORE the
+   * executor's launch persist() (which loads then saves the state file),
+   * or the executor would write back the stale planMode=true.
+   */
+  async function exitReadOnlyModes(
+    notify: (msg: string, level?: 'info' | 'warning' | 'error') => void,
+  ): Promise<void> {
+    if (specMode) await exitSpecMode(notify)
+    if (planMode) await exitPlanMode(notify)
+    // A fire-and-forget exit (e.g. the Ctrl+Alt+A shortcut) may still be
+    // persisting planMode=false: await the pending persist so the launch's
+    // loadState (which reads the file directly) cannot read it back stale
+    // and write it over the flag.
+    await pendingModePersist
   }
 
   // ------------------------------------------------------------------ commands
@@ -309,7 +342,7 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
           return
         }
       }
-      if (planMode) exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+      if (planMode) void exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
       enterSpecMode((m, l) => c.ui.notify(m, l ?? 'info'), raw || undefined)
     },
   })
@@ -318,8 +351,8 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
   // without launching a workflow.
   const approveHandler = async (_args: string, c: ExtensionCommandContext) => {
     ctx = c
-    if (specMode) exitSpecMode((m, l) => c.ui.notify(m, l ?? 'info'))
-    else if (planMode) exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+    if (specMode) await exitSpecMode((m, l) => c.ui.notify(m, l ?? 'info'))
+    else if (planMode) await exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
     else c.ui.notify('adx: already in build mode (plan mode is off)', 'info')
   }
   pi.registerCommand('adx-approve', {
@@ -331,7 +364,7 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
   // configured default one, or an explicit workflow id as the first token.
   const runHandler = async (args: string, c: ExtensionCommandContext) => {
     ctx = c
-    exitReadOnlyModes((m, l) => c.ui.notify(m, l ?? 'info'))
+    await exitReadOnlyModes((m, l) => c.ui.notify(m, l ?? 'info'))
     // First bare token (no '=') names the workflow; the rest are key=value params.
     const tokens = (args ?? '').trim().split(/\s+/).filter(Boolean)
     const first = tokens[0]
@@ -488,22 +521,59 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
     description: 'Toggle adx plan/spec mode (spec mode exits; plan mode enters/toggles)',
     handler: async (c) => {
       ctx = c
-      if (specMode) exitSpecMode((m, l) => c.ui.notify(m, l ?? 'info'))
-      else if (planMode) exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+      if (specMode) await exitSpecMode((m, l) => c.ui.notify(m, l ?? 'info'))
+      else if (planMode) await exitPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
       else enterPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
     },
   })
 
   // ------------------------------------------------------------------ events
-  pi.on('session_start', async (_event, c) => {
+  pi.on('session_start', async (event, c) => {
     ctx = c
     sessionId = c.sessionManager.getSessionId()
     // First run: give the user a ready-to-edit config file with the defaults.
     const created = ensureUserConfig()
     if (created) c.ui.notify(`adx: created default config at ${created} (edit to customize)`, 'info')
     config = loadConfig(c.cwd)
-    // Restore this session's persisted state (per-session file: resuming a
-    // session brings back its plan/run; a new session starts fresh).
+
+    if (event.reason === 'new' || event.reason === 'fork') {
+      // /new or fork: a brand-new session starts 100% clean — no legacy
+      // adoption, no execution restore, no plan/spec mode inherited from a
+      // state file. The previous session's in-flight run (if any) stays in
+      // ITS per-session state file and is picked up by re-resuming that
+      // session. Config-driven entry (auto / defaultPlanMode) still applies.
+      setLegacyAdoption(false)
+      executor.resetForNewSession()
+      // The closure (and the widget's mode badge) lives for the whole pi
+      // process, so also drop the PREVIOUS session's in-memory mode state —
+      // without this, /new after a plan/spec session would start the new
+      // session still in read-only mode (prompt section + tool blocking +
+      // footer badge all inherited).
+      autoMode = false
+      if (planMode || specMode) {
+        const saved = planMode ? toolsBeforePlanMode : toolsBeforeSpecMode
+        planMode = false
+        specMode = false
+        specPath = undefined
+        toolsBeforePlanMode = undefined
+        toolsBeforeSpecMode = undefined
+        pendingModePersist = Promise.resolve()
+        pi.setActiveTools(getBuildModeTools(saved ?? pi.getActiveTools()))
+        showBadge(undefined)
+      }
+      if (pi.getFlag('adx-auto') === true || config.autoMode === true) {
+        autoMode = true
+        enterPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+      } else if (config.defaultPlanMode === true) {
+        enterPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
+      }
+      return
+    }
+
+    // resume / startup / reload: restore this session's persisted state
+    // (per-session file; a legacy in-flight run is adopted as a one-time
+    // migration, resuming the plan/run from the last stop).
+    setLegacyAdoption(true)
     const state = await loadState(c.cwd, sessionId)
     if (state.execution && state.execution.status !== 'done') {
       c.ui.notify(`adx: restoring workflow "${state.execution.workflowName}" (status: ${state.execution.status})`, 'info')
@@ -520,6 +590,10 @@ export default function adxWorkflowExtension(pi: ExtensionAPI): void {
     } else if (state.planMode === true) {
       // The session was stopped mid-plan: restore plan mode so the user can
       // pick up the unfinished plan (criteria are already in the state file).
+      // A finished run leaves planMode=false (the launch path persists it
+      // before the first executor persist), so this only fires for a plan
+      // that was genuinely left open — including a fresh plan started after
+      // a previous run finished.
       enterPlanMode((m, l) => c.ui.notify(m, l ?? 'info'))
       c.ui.notify('adx: plan mode restored (unfinished plan from last stop — continue with flow_meta, then /adx-run)', 'info')
     } else if (state.specMode === true) {

package/src/store.ts

@@ -265,6 +265,24 @@ async function adoptLegacy(cwd: string, sessionId: string): Promise<FlowState |
 
 let versionNotified = false
 
+/**
+ * Legacy shared-file adoption switch — enabled only while a RESUMED session
+ * ("startup"/"resume" session_start) loads state: a legacy in-flight run in
+ * the shared state.json is then adopted as a one-time migration for sessions
+ * created before per-session state existed. Brand-new sessions (/new, fork)
+ * run with it disabled: they start 100% clean, so a stale in-flight legacy
+ * run cannot auto-execute in them (it stays in the previous session's own
+ * state file, resumable by re-resuming that session).
+ */
+let legacyAdoption = true
+export function setLegacyAdoption(enabled: boolean): void {
+  legacyAdoption = enabled
+}
+/** Current adoption gate (the widget's legacy fallback mirrors the store's). */
+export function legacyAdoptionEnabled(): boolean {
+  return legacyAdoption
+}
+
 export async function loadState(cwd: string, sessionId?: string): Promise<FlowState> {
   const parsed = await readRaw(stateFileFor(cwd, sessionId))
   if (parsed !== undefined) {
@@ -278,8 +296,9 @@ export async function loadState(cwd: string, sessionId?: string): Promise<FlowSt
     }
     return normalizeState(parsed)
   }
-  // New per-session file: try to adopt a legacy in-flight run (shared state.json).
-  if (sessionId && process.env.ADX_CHILD !== '1') {
+  // New per-session file: try to adopt a legacy in-flight run (shared
+  // state.json) — only for resumed sessions (see setLegacyAdoption).
+  if (sessionId && process.env.ADX_CHILD !== '1' && legacyAdoption) {
     const adopted = await adoptLegacy(cwd, sessionId)
     if (adopted) return adopted
   }

package/src/tools.ts

@@ -278,8 +278,13 @@ export interface FlowPlanDoneDeps {
   launch: (workflow: 'build' | 'build-verify', args: string) => Promise<void>
   /** Apply the config's skipReview default to launch args. */
   withConfigDefaults: (rawArgs: string) => string
-  /** Exit plan mode (restore build tools, clear badge) + notify. */
-  exitPlanMode: () => void
+  /**
+   * Exit plan mode (restore build tools, clear badge) + notify. Awaited
+   * before launching: the planMode=false persist must land before the
+   * executor's launch persist() (load + save), or the stale flag would be
+   * written back over it.
+   */
+  exitPlanMode: () => Promise<void>
   /**
    * "Spec only — stop": compose a spec markdown from the stored criteria,
    * write it to the default .pi/specs/<slug>.md, return the written path.
@@ -313,7 +318,7 @@ export function createFlowPlanDoneTool(deps: FlowPlanDoneDeps) {
     ) {
       if (deps.autoMode()) {
         // Unattended pipeline: straight into build-verify, no dialogs.
-        deps.exitPlanMode()
+        await deps.exitPlanMode()
         deps.notify('adx: auto mode — planning complete, launching build-verify (no review)', 'info')
         await deps.launch('build-verify', 'auto=true skip_review=true')
         return {
@@ -369,7 +374,7 @@ export function createFlowPlanDoneTool(deps: FlowPlanDoneDeps) {
         // Export the stored criteria as a spec document and stop here:
         // exit plan mode, launch nothing.
         const path = await deps.specOnly()
-        deps.exitPlanMode()
+        await deps.exitPlanMode()
         deps.notify(`adx: spec saved to ${path} — no build launched`, 'info')
         return {
           content: [
@@ -400,7 +405,7 @@ export function createFlowPlanDoneTool(deps: FlowPlanDoneDeps) {
         const locArg = `worklocation=${loc.startsWith('Work in current') ? 'current' : 'new'}`
         args = workflow === 'build-verify' ? deps.withConfigDefaults(locArg) : locArg
       }
-      deps.exitPlanMode()
+      await deps.exitPlanMode()
       deps.notify(`adx: launching ${workflow}${args ? ` (${args})` : ''}`, 'info')
       await deps.launch(workflow, args)
       return {

package/src/widgets.ts

@@ -14,12 +14,34 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent'
-import { stateFileFor, type FlowState } from './store.js'
+import { stateFileFor, legacyAdoptionEnabled, type FlowState } from './store.js'
 
 const ADX_KEY = 'adx-flow' // single shared key (widget + status line) — was two identical constants
 
+/** Read-only mode the footer badge advertises. */
+export type ModeKind = 'plan' | 'auto' | 'spec'
+/**
+ * Footer mode badge, stored as a spec (mode + detail) rather than a
+ * pre-cooked ANSI string, so it re-renders with the *current* theme on
+ * every widget refresh — a mid-session theme switch leaves no stale colors.
+ */
+export interface ModeBadgeSpec {
+  mode: ModeKind
+  /** Rest of the badge line, e.g. "read-only · /adx-approve to exit". */
+  detail: string
+}
+/**
+ * Per-mode chip styling: theme token pair (foreground text + background
+ * fill). The bg tokens are optional in user themes — a missing/empty token
+ * degrades the chip to bold colored text (graceful, still distinct).
+ */
+const MODE_CHIP_STYLES: Record<ModeKind, { tag: string; fg: string; bg: string }> = {
+  plan: { tag: '[PLAN]', fg: 'warning', bg: 'toolPendingBg' },
+  auto: { tag: '[AUTO]', fg: 'accent', bg: 'selectedBg' },
+  spec: { tag: '[SPEC]', fg: 'success', bg: 'toolSuccessBg' },
+}
 /** Current mode badge shown in the footer (set by the extension on mode changes). */
-let modeBadge: string | undefined
+let modeBadge: ModeBadgeSpec | undefined
 
 /** Spinner frames for the sub-agent activity widget. */
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
@@ -64,7 +86,7 @@ function readRaw(path: string): FlowState | undefined {
 function readState(cwd: string, sessionId?: string): FlowState | undefined {
   const state = readRaw(stateFileFor(cwd, sessionId))
   if (state) return state
-  if (sessionId && process.env.ADX_CHILD !== '1') {
+  if (sessionId && process.env.ADX_CHILD !== '1' && legacyAdoptionEnabled()) {
     const legacy = readRaw(join(cwd, '.pi', 'adx-flow', 'state.json'))
     if (legacy?.execution && legacy.execution.status !== 'done' && !legacy.execution.migratedTo) {
       return legacy
@@ -84,26 +106,56 @@ function truncate(text: string, max: number): string {
   return text.length > max ? text.slice(0, max - 1) + '…' : text
 }
 
+/** Minimal theme surface used for footer styling (full Theme in the TUI,
+ *  PLAIN_THEME fallback elsewhere). `bg` is optional: test fakes and
+ *  older contexts may lack it. */
+interface ThemeLike {
+  // `any` color: the real Theme takes a ThemeColor token union, the plain
+  // fallback takes anything — `any` keeps both assignable.
+  fg: (color: any, text: string) => string
+  bold: (text: string) => string
+  strikethrough: (text: string) => string
+  bg?: (color: any, text: string) => string
+}
 /** Theme fallback for contexts without `ui.theme` (non-interactive modes, tests). */
-const PLAIN_THEME = {
-  fg: (_color: string, text: string): string => text,
-  bold: (text: string): string => text,
-  strikethrough: (text: string): string => text,
+const PLAIN_THEME: ThemeLike = {
+  fg: (_color, text) => text,
+  bold: (text) => text,
+  strikethrough: (text) => text,
+  bg: (_color, text) => text,
+}
+/** Current theme, or the plain-text fallback. */
+function themeFor(ui: { theme?: ThemeLike }): ThemeLike {
+  return ui.theme ?? PLAIN_THEME
+}
+/**
+ * Render the footer mode badge: a themed chip (bold colored tag on a
+ * background fill, per mode) + muted detail text. Plain text when the
+ * theme is absent. The literal tag ([PLAN]/[AUTO]/[SPEC]) is preserved
+ * around the ANSI codes (e2e checks rely on it).
+ */
+function renderModeBadge(theme: ThemeLike, spec: ModeBadgeSpec): string {
+  const s = MODE_CHIP_STYLES[spec.mode]
+  const inner = ` ${theme.fg(s.fg, theme.bold(s.tag))} `
+  const chip = theme.bg ? theme.bg(s.bg, inner) : inner
+  // The chip is padded on both sides, so the prefix carries no trailing
+  // space (avoids the doubled 'adx:  [PLAN]' gap).
+  return `adx:${chip}${spec.detail ? ` ${theme.fg('muted', spec.detail)}` : ''}`
 }
 
 /** Render the adx-flow widget (criteria + step) or clear it when idle. */
 export function refreshFlowWidget(ctx: ExtensionContext, sessionId?: string): void {
   const state = readState(ctx.cwd, sessionId)
   const ui = ctx.ui
+  const theme = themeFor(ui)
 
   if (!state || (!state.execution && Object.keys(state.metadata).length === 0)) {
     ui.setWidget(ADX_KEY, undefined)
-    ui.setStatus(ADX_KEY, modeBadge)
+    ui.setStatus(ADX_KEY, modeBadge ? renderModeBadge(theme, modeBadge) : undefined)
     return
   }
 
   const lines: string[] = []
-  const theme = ui.theme ?? PLAIN_THEME
 
   // Header: workflow + step + iteration
   if (state.execution) {
@@ -151,28 +203,31 @@ export function refreshFlowWidget(ctx: ExtensionContext, sessionId?: string): vo
 
   ui.setWidget(ADX_KEY, lines)
 
-  // Footer status line (compact)
+  // Footer status line (compact, theme-styled)
   if (state.execution) {
     const passed = criteria.filter((c) => c.status === 'passed').length
+    const name = theme.fg('accent', state.execution.workflowName)
     const footer =
       state.execution.status === 'done'
-        ? `✅ adx: ${state.execution.workflowName} done`
-        : `adx: ${state.execution.workflowName} · ${state.execution.currentStep} · ${passed}/${criteria.length || 0} criteria`
+        ? `${theme.fg('success', '✅')} adx: ${name} ${theme.fg('muted', 'done')}`
+        : `adx: ${name} ${theme.fg('muted', `· ${state.execution.currentStep} · ${passed}/${criteria.length || 0} criteria`)}`
     ui.setStatus(ADX_KEY, footer)
   } else if (modeBadge) {
-    ui.setStatus(ADX_KEY, modeBadge)
+    ui.setStatus(ADX_KEY, renderModeBadge(theme, modeBadge))
   } else {
     ui.setStatus(ADX_KEY, undefined)
   }
 }
 
 /**
- * Set (or clear) the footer mode badge, e.g. `adx: [PLAN] read-only`.
+ * Set (or clear) the footer mode badge, e.g. the `[PLAN]` chip +
+ * "read-only · /adx-approve to exit". The spec is stored and re-rendered
+ * with the current theme on every refresh (theme switches stay in sync).
  * The badge survives widget refreshes while no workflow is running; an
  * active workflow's status line takes precedence over it (a finished run
  * does not block the badge).
  */
-export function setModeBadge(ctx: ExtensionContext, badge: string | undefined, sessionId?: string): void {
+export function setModeBadge(ctx: ExtensionContext, badge: ModeBadgeSpec | undefined, sessionId?: string): void {
   modeBadge = badge
   const state = readState(ctx.cwd, sessionId)
   const active =
@@ -181,7 +236,7 @@ export function setModeBadge(ctx: ExtensionContext, badge: string | undefined, s
     if (!active) ctx.ui.setStatus(ADX_KEY, undefined)
     return
   }
-  if (!active) ctx.ui.setStatus(ADX_KEY, badge)
+  if (!active) ctx.ui.setStatus(ADX_KEY, renderModeBadge(themeFor(ctx.ui), badge))
 }
 
 /** Clear the widget + status (e.g. on /adx-cancel). */
@@ -310,6 +365,6 @@ export function setSubAgentActivity(
 
   ui.setStatus(
     ADX_KEY,
-    `adx: ${activity.agent} · "${activity.step}" running…`,
+    `adx: ${themeFor(ui).fg('accent', activity.agent)} ${themeFor(ui).fg('muted', `· "${activity.step}" running…`)}`,
   )
 }