@nanhara/hara 0.126.1 → 0.127.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.127.1 — 2026-07-20 — managed access lifecycle
+
+- Managed enrollment now persists the control plane's authoritative device-token expiry. Hara warns
+  during the final 24 hours, reports the boundary in `whoami`/`enroll --status`, and fails closed with
+  a focused re-enrollment command once access expires or lifecycle data is corrupt.
+- Serve provider settings expose only expiry metadata—not the token—so Hara Desktop can distinguish
+  an authenticated managed route from an expired one.
+- Upgrade with `npm i -g @nanhara/hara@0.127.1`.
+
+## 0.127.0 — 2026-07-20 — structured context and typed task lifecycle
+
+- **Prompt assembly is now an explicit, ordered runtime layer.** Cache-stable policy, tool, project, and
+  session context are separated from turn-specific execution state and memory digests, deduplicated, and
+  assembled in a deterministic order. Anthropic requests preserve a stable cache prefix while other
+  providers continue to receive the same complete system contract.
+- **Conversation and execution state now travel on separate protocol planes.** Authenticated Serve clients
+  can negotiate the versioned `event.task_state` stream for running, waiting, paused, completed, and blocked
+  work, with stable task/turn identities, phases, accepted task briefs, checkpoints, approvals, outcomes,
+  restore snapshots, and explicit stop/finish transitions.
+- **Mid-turn input uses expected-turn steering.** `session.steer` durably accepts an update only for the
+  intended live turn, so Desktop and other clients can distinguish a real refinement from the next queued
+  task without parsing model prose or losing an end-of-turn race.
+- Ambient lifecycle events never include command or path previews, and resumed client history removes the
+  internal steering-triage wrapper before display. Detailed tool output remains confined to the explicit
+  conversation surface.
+- Upgrade with `npm i -g @nanhara/hara@0.127.0`.
+
 ## 0.126.1 — 2026-07-19 — verified plugin packages and ownership-safe lifecycle
 
 - **Plugin packages now fail closed at staging.** Hara validates a bounded manifest schema, portable IDs and

package/dist/agent/loop.js

@@ -24,6 +24,7 @@ import { prepareHistoryForModel } from "./context-budget.js";
 import { rolesDigest } from "../org/roles.js";
 import { applyTaskBrief } from "../session/task.js";
 import { askUserTool } from "../tools/ask_user.js";
+import { PromptAssembler } from "./prompt.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Engine-owned, non-authority helpers. Role filters still govern every deferred target activated by
@@ -61,8 +62,7 @@ export function needsConfirm(kind, mode) {
         return kind === "exec";
     return true; // suggest: confirm edits and exec
 }
-const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's terminal.
-Working directory: ${cwd}
+const HARA_SYSTEM = () => `You are hara, a coding agent running in the user's terminal.
 Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
 them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
@@ -153,8 +153,9 @@ const CONTINUATION_SYSTEM = "# Existing-session continuity\n" +
     "re-inventory the workspace, or summarize files merely to understand what happened before. Follow the latest user request " +
     "and reuse prior conclusions and tool results. Inspect files only when the latest request requires it. If the working " +
     "directory is Home, ask the user to start Hara from a concrete project instead of enumerating Home or its children.";
-function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext, intake) {
-    const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
+export function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext, intake) {
+    const assembler = new PromptAssembler();
+    assembler.add("core", "static", "core", override || HARA_SYSTEM());
     const skills = skillsDigest(cwd);
     const roles = override ? "" : rolesDigest(cwd);
     const intakeContext = !intake?.enabled
@@ -176,15 +177,17 @@ function composeSystem(cwd, projectContext, override, memory, continuationSessio
                 "the interpreted goal, intent, constraints, acceptance checks, and short steps. Use intent `answer` " +
                 "for a direct answer, `investigate` for evidence gathering/diagnosis, and `change` when the user asked " +
                 "you to modify or deliver something. Do not claim completion until the acceptance checks are verified.");
-    return (head +
-        gatewayNote() +
-        (continuationSession ? `\n\n${CONTINUATION_SYSTEM}` : "") +
-        (executionContext ? `\n\n${executionContext}` : "") +
-        intakeContext +
-        (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
-        (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
-        (roles ? `\n\n# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "") +
-        (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
+    assembler
+        .add("working-directory", "session", "runtime", `Working directory: ${cwd}`)
+        .add("gateway-channel", "session", "channel", gatewayNote())
+        .add("continuation", "session", "task", continuationSession ? CONTINUATION_SYSTEM : "")
+        .add("execution", "session", "task", executionContext)
+        .add("project", "session", "project", projectContext ? `# Project context (AGENTS.md)\n${projectContext}` : "")
+        .add("memory", "session", "memory", memory ? `# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "")
+        .add("roles", "session", "role", roles ? `# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "")
+        .add("skills", "session", "skill", skills ? `# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : "")
+        .add("task-intake", "turn", "task", intakeContext);
+    return assembler.build();
 }
 const RUN_STOPPED = Symbol("agent-run-stopped");
 const REPEATED_FAILURE_LIMIT = 3;
@@ -618,7 +621,8 @@ async function runAgentInner(history, opts, life) {
             ? [...baseSpecs, ...runExtraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
             : baseSpecs;
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
-        const system = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext, { enabled: !!opts.taskIntake, brief: intakeTask?.brief });
+        const assembledSystem = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext, { enabled: !!opts.taskIntake, brief: intakeTask?.brief });
+        const system = assembledSystem.text;
         const prepared = prepareHistoryForModel(history, {
             model: activeProvider.model,
             system,
@@ -714,6 +718,7 @@ async function runAgentInner(history, opts, life) {
                 }
                 return activeProvider.turn({
                     system,
+                    systemParts: assembledSystem.parts,
                     history: prepared.history,
                     tools: specs,
                     // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a

package/dist/agent/prompt.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+const STABILITY_ORDER = {
+    static: 0,
+    session: 1,
+    turn: 2,
+};
+function promptDigest(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+/** Assemble the model's runtime context as a governed object instead of an ever-growing string.
+ *
+ * Ordering is intentionally monotonic. If a caller tries to place stable material after a dynamic task
+ * suffix, fail during assembly instead of silently destroying provider prefix-cache locality. */
+export class PromptAssembler {
+    parts = [];
+    ids = new Set();
+    lastStability = "static";
+    add(id, stability, source, content) {
+        const normalizedId = id.trim();
+        const normalizedContent = content?.trim();
+        if (!normalizedContent)
+            return this;
+        if (!normalizedId)
+            throw new Error("system prompt part id must not be empty");
+        if (this.ids.has(normalizedId))
+            throw new Error(`duplicate system prompt part id: ${normalizedId}`);
+        if (this.parts.length && STABILITY_ORDER[stability] < STABILITY_ORDER[this.lastStability]) {
+            throw new Error(`system prompt part '${normalizedId}' (${stability}) cannot follow ${this.lastStability} context`);
+        }
+        this.ids.add(normalizedId);
+        this.lastStability = stability;
+        this.parts.push({
+            id: normalizedId,
+            stability,
+            source,
+            content: normalizedContent,
+            digest: promptDigest(normalizedContent),
+        });
+        return this;
+    }
+    build() {
+        const parts = this.parts.map((part) => ({ ...part }));
+        return {
+            text: parts.map((part) => part.content).join("\n\n"),
+            parts,
+        };
+    }
+}

package/dist/index.js

@@ -22,7 +22,7 @@ import { notifyDone } from "./notify.js";
 import { startMcpServer, mcpServeToolNames } from "./mcp/server.js";
 import { completionScript } from "./completions.js";
 import { renderSessionMarkdown } from "./export.js";
-import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles } from "./org-fleet/enroll.js";
+import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles, deviceTokenExpired, deviceTokenExpiryWarning, } from "./org-fleet/enroll.js";
 import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile, removeProfile, setModel as setProfileModel, resetModel as resetProfileModel, getProfile, effectiveModel, routingLabel, routeHost, activeId, resolveActive, setFlagOverride, writePin, removePin, pinFilePath, DEFAULT_ORG_ID, PERSONAL_ID, } from "./profile/profile.js";
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
@@ -134,7 +134,7 @@ async function buildProvider(cfg, targetOverride) {
     // requests" — gateway (deviceToken at the gateway) vs BYOK (user's key direct to the provider).
     const { profile: ap } = profileForConfig(cfg);
     if (ap.kind === "gateway") {
-        if (!ap.gatewayUrl || !ap.deviceToken)
+        if (!ap.gatewayUrl || !ap.deviceToken || deviceTokenExpired(ap.tokenExpiresAt))
             return null;
         const baseURL = ap.baseURL || `${ap.gatewayUrl.replace(/\/$/, "")}/v1`;
         const model = resolveGatewayModel(cfg, ap, process.env, targetOverride?.model);
@@ -193,8 +193,12 @@ async function buildGuardian(cfg, primary) {
 }
 function authHint(cfg) {
     const { profile: ap } = profileForConfig(cfg);
-    if (ap.kind === "gateway")
+    if (ap.kind === "gateway") {
+        if (deviceTokenExpired(ap.tokenExpiresAt)) {
+            return `Active profile '${ap.id}' has expired organization access — re-enroll with \`hara profile add ${ap.id} --gateway ${ap.gatewayUrl || "<url>"} --code <code>\`.`;
+        }
         return `Active profile '${ap.id}' is a gateway profile but is missing deviceToken — re-enroll with \`hara profile add ${ap.id} --gateway <url> --code <code>\`.`;
+    }
     const target = resolveByokProviderTarget(cfg, ap, false);
     const provider = target.provider;
     if (provider === "qwen-oauth")
@@ -215,6 +219,7 @@ function providerSettingsSnapshot(targetCwd) {
     const catalog = providerCatalog();
     if (profile.kind === "gateway") {
         const entry = catalog.find((candidate) => candidate.id === "hara-gateway");
+        const tokenExpired = deviceTokenExpired(profile.tokenExpiresAt);
         return {
             current: {
                 provider: "hara-gateway",
@@ -223,11 +228,12 @@ function providerSettingsSnapshot(targetCwd) {
                 location: entry.location,
                 auth: entry.auth,
                 keyConfigured: !!profile.deviceToken,
-                authenticated: !!profile.gatewayUrl && !!profile.deviceToken,
+                authenticated: !!profile.gatewayUrl && !!profile.deviceToken && !tokenExpired,
                 profileId: profile.id,
                 profileKind: profile.kind,
                 profileSource: resolution.source,
                 editable: false,
+                ...(profile.tokenExpiresAt ? { tokenExpiresAt: profile.tokenExpiresAt, tokenExpired } : {}),
             },
             providers: catalog,
         };
@@ -1664,6 +1670,11 @@ function printWhoami() {
             out(c.dim(`  device:   ${p.deviceId.length > 8 ? "…" + p.deviceId.slice(-8) : p.deviceId}\n`));
         if (p.availableModels?.length)
             out(c.dim(`  available: ${p.availableModels.join(", ")}\n`));
+        if (p.tokenExpiresAt)
+            out(c.dim(`  expires:  ${p.tokenExpiresAt}\n`));
+        const warning = deviceTokenExpiryWarning(p.tokenExpiresAt);
+        if (warning)
+            out(c.yellow(`  ⚠ ${warning}\n`));
     }
     else {
         out(c.dim(`  provider: ${p.provider}\n`));
@@ -1795,6 +1806,7 @@ profileCmd
                 defaultModel: e.model || "",
                 availableModels: e.model ? [e.model] : [],
                 enrolledAt: e.enrolledAt,
+                tokenExpiresAt: e.expiresAt,
             };
             upsertProfile(p); // upsert: re-enrolling the same id rotates the token
             const r = useProfile(id);
@@ -1982,8 +1994,8 @@ program
     .option("--clear", "switch active profile back to personal (does NOT delete the gateway profile)")
     .action(async (gatewayUrl, opts) => {
     if (opts.status) {
-        const p = loadActiveProfile();
-        return void out(p.kind === "gateway" ? c.green("enrolled") + c.dim(` · ${p.gatewayUrl} · device ${p.deviceId || "?"} · model ${effectiveModel(p) || "(gateway default)"} · since ${p.enrolledAt || "?"}\n`) : c.dim("Not enrolled — `hara enroll <gateway-url> --code <code>`.\n"));
+        printWhoami();
+        return;
     }
     if (opts.clear) {
         // Behavior change: don't *delete* the gateway profile (keeps the token around for re-use);
@@ -2010,6 +2022,7 @@ program
             defaultModel: e.model || "",
             availableModels: e.model ? [e.model] : [],
             enrolledAt: e.enrolledAt,
+            tokenExpiresAt: e.expiresAt,
         };
         upsertProfile(p);
         useProfile(DEFAULT_ORG_ID);
@@ -3093,6 +3106,11 @@ program.action(async (opts) => {
     // to suppress everywhere.
     if (!opts.print && process.env.HARA_QUIET !== "1") {
         out(c.dim(activeProfileLine(__activeP)) + "\n");
+        const expiryWarning = __activeP.kind === "gateway"
+            ? deviceTokenExpiryWarning(__activeP.tokenExpiresAt)
+            : null;
+        if (expiryWarning)
+            out(c.yellow(`⚠ ${expiryWarning}\n`));
     }
     if (__activeP.kind === "gateway" || cfg.provider === "hara-gateway") {
         void heartbeat(); // fleet visibility — fire-and-forget, never blocks startup

package/dist/org-fleet/enroll.js

@@ -5,7 +5,7 @@
 // plane fleet visibility. Token + endpoint live in ~/.hara/org.json (0600).
 //
 // Protocol (what `hara-control` implements on the other end):
-//   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?}
+//   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?, expires_at?}
 //   POST {gateway}/v1/heartbeat   Bearer <device_token> {device_id, name, os, hara_version} -> 200/204
 //   GET  {gateway}/v1/roles       Bearer <device_token> -> {version, org_policy, roles:[…]}  (B3 digital-employee push-down)
 //   POST {gateway}/v1/chat/completions  (OpenAI-compatible; the normal agent traffic, Bearer <device_token>)
@@ -45,6 +45,7 @@ export function loadEnrollment() {
                 model: ap.defaultModel || "",
                 baseURL: ap.baseURL,
                 enrolledAt: ap.enrolledAt || new Date().toISOString(),
+                expiresAt: ap.tokenExpiresAt,
             };
         }
     }
@@ -70,6 +71,14 @@ export function parseEnrollResponse(gatewayUrl, j, now) {
     const deviceToken = (j.device_token ?? j.deviceToken);
     if (!deviceToken)
         throw new Error("enroll response missing device_token");
+    const rawExpiresAt = j.expires_at ?? j.expiresAt;
+    let expiresAt;
+    if (rawExpiresAt !== undefined && rawExpiresAt !== null) {
+        if (typeof rawExpiresAt !== "string" || !Number.isFinite(Date.parse(rawExpiresAt))) {
+            throw new Error("enroll response contains an invalid expires_at");
+        }
+        expiresAt = new Date(rawExpiresAt).toISOString();
+    }
     return {
         gatewayUrl: gatewayUrl.replace(/\/$/, ""),
         deviceToken,
@@ -77,8 +86,36 @@ export function parseEnrollResponse(gatewayUrl, j, now) {
         model: String(j.model ?? ""),
         baseURL: (j.base_url ?? j.baseURL),
         enrolledAt: now,
+        expiresAt,
     };
 }
+/** Legacy control planes did not advertise token expiry, so absence remains compatible. New control
+ * planes provide it and the CLI can fail early with an actionable re-enrollment message. */
+export function deviceTokenExpired(expiresAt, now = new Date()) {
+    if (!expiresAt)
+        return false;
+    const expiryMs = Date.parse(expiresAt);
+    // A present-but-corrupt lifecycle boundary must not silently become a legacy non-expiring token.
+    return !Number.isFinite(expiryMs) || expiryMs <= now.getTime();
+}
+/** Only warn near the boundary; healthy week-long tokens should not add startup noise. */
+export function deviceTokenExpiryWarning(expiresAt, now = new Date()) {
+    if (!expiresAt)
+        return null;
+    const expiryMs = Date.parse(expiresAt);
+    if (!Number.isFinite(expiryMs))
+        return "organization access expiry is unreadable; re-enroll this profile";
+    const remainingMs = expiryMs - now.getTime();
+    if (remainingMs <= 0)
+        return "organization access expired; re-enroll this profile before running a task";
+    if (remainingMs > 24 * 60 * 60_000)
+        return null;
+    const remainingMinutes = Math.max(1, Math.ceil(remainingMs / 60_000));
+    const remaining = remainingMinutes < 60
+        ? `${remainingMinutes}m`
+        : `${Math.ceil(remainingMinutes / 60)}h`;
+    return `organization access expires in ${remaining}; ask your admin for a new enrollment code`;
+}
 /** Exchange a one-time code for a device token at the gateway, persist it, and return the Enrollment. */
 export async function enrollDevice(gatewayUrl, code, signal) {
     const base = gatewayUrl.replace(/\/$/, "");

package/dist/profile/profile.js

@@ -98,6 +98,7 @@ function readDefaultOrgFromOrgJson(e) {
         defaultModel,
         availableModels: defaultModel ? [defaultModel] : [],
         enrolledAt: e.enrolledAt || new Date().toISOString(),
+        tokenExpiresAt: typeof e.expiresAt === "string" ? e.expiresAt : undefined,
     };
 }
 /** First-time migration. Idempotent — running again is a no-op (profiles.json already present). */

package/dist/providers/anthropic.js

@@ -56,13 +56,14 @@ const CACHE = { type: "ephemeral" };
  *  conversation prefix FROM CACHE instead of re-billing + re-processing the whole prompt — the single
  *  biggest latency + cost win as history grows (uncached, a long session pays full input every turn).
  *
- *  Anthropic caps breakpoints at 4 and orders the cache prefix `tools → system → messages`, so a mark
- *  on `system` already caches tools+system (the big static block) in one shot. We then spend up to two
- *  rolling marks near the message tail: the last message (so THIS turn's full prefix is written) and one
- *  ~2 back (so the NEXT turn — which appends new messages — still finds a long cached prefix to read).
+ *  Anthropic caps breakpoints at 4 and orders the cache prefix `tools → system → messages`. Structured Hara
+ *  prompts spend up to two marks on the static and session boundaries, leaving the changing turn suffix
+ *  uncached; legacy strings keep one system mark. We then spend up to two rolling marks near the message
+ *  tail: the last message (so THIS turn's full prefix is written) and one ~2 back (so the NEXT turn — which
+ *  appends new messages — still finds a long cached prefix to read).
  *  Mutates `messages` in place (toAnthropic hands us a fresh array each turn); returns the request-shaped
  *  system. Exported pure for tests. */
-export function applyCacheControl(system, messages) {
+export function applyCacheControl(system, messages, systemParts) {
     const mark = (m) => {
         if (typeof m.content === "string") {
             if (m.content.length)
@@ -80,7 +81,29 @@ export function applyCacheControl(system, messages) {
     for (const i of idxs)
         mark(messages[i]);
     // Only cache system when it's substantial enough to matter (an empty text block would 400).
-    const cachedSystem = system ? [{ type: "text", text: system, cache_control: CACHE }] : system;
+    let cachedSystem = system;
+    const renderedParts = systemParts?.map((part) => part.content).join("\n\n");
+    if (system && systemParts?.length && renderedParts === system) {
+        const sections = [];
+        for (const part of systemParts) {
+            const tail = sections.at(-1);
+            if (tail?.stability === part.stability)
+                tail.text += `\n\n${part.content}`;
+            else
+                sections.push({ stability: part.stability, text: part.content });
+        }
+        cachedSystem = sections.map((section, index) => ({
+            type: "text",
+            // Anthropic concatenates adjacent text blocks directly. Preserve the authoritative rendered string
+            // byte-for-byte across our cache boundaries.
+            text: section.text + (index < sections.length - 1 ? "\n\n" : ""),
+            ...(section.stability === "turn" ? {} : { cache_control: CACHE }),
+        }));
+    }
+    else if (system) {
+        // Legacy/custom callers still receive the original single cached system block.
+        cachedSystem = [{ type: "text", text: system, cache_control: CACHE }];
+    }
     return { system: cachedSystem, messages };
 }
 /** Anthropic models whose only valid `thinking` setting is `{type: "adaptive"}` — they reject any
@@ -116,9 +139,9 @@ export function createAnthropicProvider(opts) {
     return {
         id: "anthropic",
         model: opts.model,
-        async turn({ system, history, tools, onText, onReasoning, signal }) {
+        async turn({ system, systemParts, history, tools, onText, onReasoning, signal }) {
             const thinking = buildThinkingParam(opts.model, opts.reasoningEffort);
-            const { system: cachedSystem, messages } = applyCacheControl(system, toAnthropic(history));
+            const { system: cachedSystem, messages } = applyCacheControl(system, toAnthropic(history), systemParts);
             const stream = client.messages.stream({
                 model: opts.model,
                 max_tokens: 32000,

package/dist/serve/protocol.js

@@ -33,6 +33,8 @@
 // Server → client notifications (all carry sessionId):
 //   event.text / event.reasoning {delta} · event.tool {name,preview} · event.diff {text}
 //   event.notice {text} · event.turn_end {reply,usage,error?} · approval.request {approvalId,question}
+//   event.task_state {version,taskId,turnId,objective,state,taskStatus,phase,checkpoint,…}
+//                     authoritative execution plane; clients feature-detect it via capabilities.events
 export const PROTOCOL_VERSION = 1;
 /** JSON-RPC error codes: standard ones plus hara-specific (-320xx). */
 export const ERR = {

package/dist/serve/server.js

@@ -27,10 +27,11 @@ import { loadJobs, addJob, removeJob, setEnabled } from "../cron/store.js";
 import { parseSchedule, describeSchedule } from "../cron/schedule.js";
 import { loadTasks } from "../tools/task.js";
 import { listPending, resolvePending } from "../gateway/flows-pending.js";
-import { disposeTodoScope, restoreTodos, serializeTodos } from "../tools/todo.js";
+import { disposeTodoScope, onTodosChange, restoreTodos, serializeTodos } from "../tools/todo.js";
 import { INTERJECT_PREFIX, disposeReminderScope } from "../agent/reminders.js";
 import { SessionHub, realStore } from "./sessions.js";
 import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } from "./protocol.js";
+import { taskLifecycleEvent } from "./task-events.js";
 import { readModelContextFileSync } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
@@ -228,8 +229,15 @@ export function lastAssistantText(history) {
 export function historyForClient(history) {
     const out = [];
     for (const m of history) {
-        if (m.role === "user")
-            out.push({ role: "user", text: m.content });
+        if (m.role === "user") {
+            const steeringPrefix = `${INTERJECT_PREFIX}\n\n`;
+            out.push({
+                role: "user",
+                text: m.content.startsWith(steeringPrefix)
+                    ? m.content.slice(steeringPrefix.length)
+                    : m.content,
+            });
+        }
         else if (m.role === "assistant" && m.text)
             out.push({ role: "assistant", text: m.text });
         // tool results are omitted — clients see live tool events; persisted detail stays in the store
@@ -333,6 +341,11 @@ export async function startServe(opts, deps) {
             if (ws.readyState === ws.OPEN)
                 ws.send(frame);
     };
+    const broadcastTaskState = (session, activity) => {
+        if (!session.task)
+            return;
+        broadcast("event.task_state", { ...taskLifecycleEvent(session.meta.id, session.task, session.meta.todos ?? [], activity) });
+    };
     // Discovery file — the desktop shell reads this to find the running server (like a pid/port file).
     const discoveryDir = join(deps.discoveryHome ?? homedir(), ".hara");
     const discoveryPath = join(discoveryDir, "serve.json");
@@ -413,13 +426,37 @@ export async function startServe(opts, deps) {
             s.busy = false;
             throw error;
         }
+        let lastTaskStateSignature = "";
+        const emitTaskState = (activity, todos = s.meta.todos ?? []) => {
+            if (!s.task)
+                return;
+            const event = taskLifecycleEvent(sessionId, s.task, todos, activity);
+            const { at: _at, ...stableEvent } = event;
+            const signature = JSON.stringify(stableEvent);
+            if (signature === lastTaskStateSignature)
+                return;
+            lastTaskStateSignature = signature;
+            broadcast("event.task_state", { ...event });
+        };
         broadcast("event.turn_start", { sessionId, taskId: s.task.id, turnId: s.task.turnId });
+        emitTaskState({ state: "running", phase: "starting" });
         const historyStart = s.history.length;
         const before = { input: s.stats.input, output: s.stats.output };
         const sink = {
-            text: (d) => broadcast("event.text", { sessionId, delta: d }),
-            reasoning: (d) => broadcast("event.reasoning", { sessionId, delta: d }),
-            tool: (name, preview) => broadcast("event.tool", { sessionId, name, preview }),
+            text: (d) => {
+                emitTaskState({ state: "running", phase: "responding" });
+                broadcast("event.text", { sessionId, delta: d });
+            },
+            reasoning: (d) => {
+                emitTaskState({ state: "running", phase: "thinking" });
+                broadcast("event.reasoning", { sessionId, delta: d });
+            },
+            tool: (name, preview) => {
+                // The task/status plane is safe for ambient surfaces such as an always-on-top companion.
+                // Command/path previews remain on the explicit event.tool transcript plane only.
+                emitTaskState({ state: "running", phase: "tool", detail: name });
+                broadcast("event.tool", { sessionId, name, preview });
+            },
             diff: (t) => broadcast("event.diff", { sessionId, text: t }),
             notice: (t) => broadcast("event.notice", { sessionId, text: t }),
         };
@@ -434,6 +471,13 @@ export async function startServe(opts, deps) {
                 clearTimeout(timer);
                 pendingApprovals.delete(approvalId);
                 signal.removeEventListener("abort", onAbort);
+                if (!signal.aborted && s.task?.status === "running") {
+                    emitTaskState({
+                        state: "running",
+                        phase: "thinking",
+                        detail: v === false ? "Approval denied; continuing safely" : "Approval granted; continuing",
+                    });
+                }
                 resolve(v);
             };
             const onAbort = () => finish(false);
@@ -445,15 +489,28 @@ export async function startServe(opts, deps) {
                 // `signal` composes the owning turn cancellation with runAgent's lifecycle cancellation. Listening
                 // only to turnAbort would leave the approval map and Desktop prompt stale after an internal stop.
                 signal.addEventListener("abort", onAbort, { once: true });
+                emitTaskState({
+                    state: "waiting",
+                    phase: "approval",
+                    detail: q,
+                    approval: { id: approvalId, question: q },
+                });
                 broadcast("approval.request", { sessionId, approvalId, question: q });
             }
         });
+        let stopTodoEvents = () => { };
         try {
             if (!(await refreshSessionProvider(s))) {
                 throw new Error(`provider not authenticated for pinned model '${s.meta.model}' at ${s.meta.cwd}`);
             }
             const turnGuardian = deps.buildGuardian ? await deps.buildGuardian(s.meta.cwd) : deps.guardian;
             restoreTodos(s.meta.todos, sessionId);
+            stopTodoEvents = onTodosChange((todos) => {
+                // Keep the session snapshot current while the turn runs. Steering and task-intake checkpoints can
+                // then publish/persist the same checklist the model just wrote instead of regressing to turn-start.
+                s.meta.todos = serializeTodos(sessionId);
+                emitTaskState({ state: "running", phase: "checkpoint" }, s.meta.todos);
+            }, sessionId);
             // Slash skills, CLI parity: "/skill-id request…" expands into the skill-entering message, so a
             // desktop composer's "/" popup triggers the exact behavior the terminal gets. Unknown ids fall
             // through as plain text (the model sees what the user typed).
@@ -495,10 +552,12 @@ export async function startServe(opts, deps) {
                         current: () => s.task,
                         onUpdate: (next) => {
                             s.task = next;
+                            emitTaskState({ state: "running", phase: "checkpoint" }, serializeTodos(sessionId));
                         },
                         onCheckpoint: (next) => {
                             s.task = next;
                             hub.save(s);
+                            emitTaskState({ state: "running", phase: "checkpoint" }, serializeTodos(sessionId));
                         },
                     },
                     pendingInput: async () => {
@@ -521,6 +580,7 @@ export async function startServe(opts, deps) {
             s.meta.todos = serializeTodos(sessionId);
             s.task = finishTaskExecution(s.task, outcome, s.meta.todos, turnAbort.signal.aborted);
             hub.save(s);
+            emitTaskState({ phase: "finished" }, s.meta.todos);
             const usage = { input: s.stats.input - before.input, output: s.stats.output - before.output };
             // context watermark rides along with every turn end (codex thread/tokenUsage/updated pattern) —
             // clients render a meter without an extra round-trip.
@@ -544,10 +604,12 @@ export async function startServe(opts, deps) {
             if (s.task?.status === "running") {
                 s.task = finishTaskExecution(s.task, { status: "error", error: error instanceof Error ? error.message : String(error) }, s.meta.todos ?? [], turnAbort.signal.aborted);
                 hub.save(s);
+                emitTaskState({ phase: "finished" }, s.meta.todos ?? []);
             }
             throw error;
         }
         finally {
+            stopTodoEvents();
             s.abort = null;
             s.busy = s.pendingProviderTurns > 0 || s.pendingToolRuns > 0;
         }
@@ -682,7 +744,7 @@ export async function startServe(opts, deps) {
                             provider: runtime.providerId,
                             model: runtime.model,
                             setupState,
-                            capabilities: { methods },
+                            capabilities: { methods, events: ["event.task_state"] },
                         }));
                     }
                     if (!authed.has(ws))
@@ -749,6 +811,7 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.INTERNAL, `provider not authenticated for pinned model '${r.session.meta.model}'`));
                             }
                             r.session.projectContext = loadAgentContext(r.session.meta.cwd) || undefined;
+                            broadcastTaskState(r.session, { phase: "restored" });
                             return reply(rpcResult(id, {
                                 sessionId: r.session.meta.id,
                                 model: r.session.meta.model,
@@ -791,12 +854,16 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.BUSY, recorded.reason));
                             s.task = recorded.task;
                             hub.save(s); // executable inbox entry is durable before ACK
+                            broadcastTaskState(s, { state: "running", phase: "steering", detail: "Steering accepted" });
                             return reply(rpcResult(id, { accepted: true, taskId: s.task.id, turnId: s.task.turnId }));
                         }
                         case "session.interrupt": {
                             const s = typeof p.sessionId === "string" ? hub.get(p.sessionId) : undefined;
                             if (!s)
                                 return reply(rpcError(id, ERR.NO_SESSION, "no such live session"));
+                            if (s.abort && s.task?.status === "running") {
+                                broadcastTaskState(s, { state: "running", phase: "stopping", detail: "Stopping at a safe boundary" });
+                            }
                             s.abort?.abort();
                             return reply(rpcResult(id, {}));
                         }

package/dist/serve/task-events.js

@@ -0,0 +1,45 @@
+export const TASK_LIFECYCLE_EVENT_VERSION = 1;
+function bounded(value, max) {
+    const normalized = value?.replace(/\s+/g, " ").trim();
+    return normalized ? normalized.slice(0, max) : undefined;
+}
+/** Build the single task-state shape consumed by Desktop, IDE clients, and the companion. Conversation
+ * streaming remains separate; this event is the authoritative execution/status plane. */
+export function taskLifecycleEvent(sessionId, task, todos = [], activity, at = new Date().toISOString()) {
+    const current = todos.find((todo) => todo.status === "in_progress")
+        ?? todos.find((todo) => todo.status === "pending");
+    const detail = bounded(activity.detail, 500);
+    const approval = activity.approval
+        ? {
+            id: activity.approval.id,
+            question: bounded(activity.approval.question, 4_000) ?? "Approval required",
+        }
+        : undefined;
+    // Runtime phases may only refine an actively running task. Once durable state reaches a terminal or
+    // resumable boundary, a late notification cannot visually resurrect it as running/waiting.
+    const state = task.status === "running"
+        ? (activity.state ?? task.status)
+        : task.status;
+    return {
+        version: TASK_LIFECYCLE_EVENT_VERSION,
+        sessionId,
+        taskId: task.id,
+        turnId: task.turnId,
+        objective: task.objective,
+        state,
+        taskStatus: task.status,
+        phase: activity.phase,
+        at,
+        updatedAt: task.updatedAt,
+        ...(task.lastOutcome ? { lastOutcome: task.lastOutcome } : {}),
+        ...(task.brief ? { brief: { intent: task.brief.intent, goal: task.brief.goal } } : {}),
+        checkpoint: {
+            done: todos.filter((todo) => todo.status === "done").length,
+            total: todos.length,
+            ...(current ? { current: bounded(current.activeForm || current.text, 300) } : {}),
+            ...(current?.owner ? { owner: bounded(current.owner, 120) } : {}),
+        },
+        ...(detail ? { detail } : {}),
+        ...(approval ? { approval } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.126.1",
+  "version": "0.127.1",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"