@nanhara/hara 0.129.0 → 0.130.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.130.0 — 2026-07-20 — ordered task-state delivery
+
+- Typed `event.task_state` notifications now carry a server-stream identity and a positive,
+  monotonically increasing sequence. Desktop and other authenticated Serve clients can reject
+  duplicated or stale lifecycle transitions instead of letting a late event overwrite the current
+  task, approval, checkpoint, or completion state.
+- Ordering spans every session and every resume within one `hara serve` process. A server restart
+  creates a new stream identity, so clients can accept the fresh sequence without confusing it with
+  an older connection.
+- Conversation streaming remains independent from execution state, and task event payloads retain
+  the same redacted ambient-data boundary. Existing protocol-v1 clients remain compatible because
+  the ordering fields are additive.
+- Upgrade with `npm i -g @nanhara/hara@0.130.0`.
+
 ## 0.129.0 — 2026-07-20 — durable revisions and workspace recovery
 
 - Authenticated Serve clients can commit a user-selected file as a new immutable Artifact revision with

package/dist/serve/protocol.js

@@ -42,7 +42,7 @@
 // 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,…}
+//   event.task_state {version,streamId,sequence,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). */

package/dist/serve/server.js

@@ -32,7 +32,7 @@ import { disposeTodoScope, onTodosChange, restoreTodos, serializeTodos } from ".
 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 { taskLifecycleEvent, } from "./task-events.js";
 import { readModelContextFileSync } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
@@ -295,6 +295,7 @@ export async function startServe(opts, deps) {
     // Physical provider/tool work can outlive its logical timeout. Keep a process-level ledger independent
     // of SessionHub membership so detach/delete cannot make an updater believe the old engine is quiescent.
     const activeOperations = new Set();
+    let taskEventSequence = 0;
     let closing = false;
     let closePromise = null;
     const trackActiveOperation = (operation) => {
@@ -358,10 +359,23 @@ export async function startServe(opts, deps) {
             if (ws.readyState === ws.OPEN)
                 ws.send(frame);
     };
+    const nextTaskEventCursor = () => {
+        const sequence = taskEventSequence + 1;
+        if (!Number.isSafeInteger(sequence)) {
+            throw new Error("task lifecycle event sequence exhausted");
+        }
+        return { streamId: instanceId, sequence };
+    };
+    const publishTaskState = (event) => {
+        // Commit the cursor immediately before the synchronous broadcast. Dedupe paths never consume one,
+        // while every published event has a unique position in this server-wide stream.
+        taskEventSequence = event.sequence;
+        broadcast("event.task_state", { ...event });
+    };
     const broadcastTaskState = (session, activity) => {
         if (!session.task)
             return;
-        broadcast("event.task_state", { ...taskLifecycleEvent(session.meta.id, session.task, session.meta.todos ?? [], activity) });
+        publishTaskState(taskLifecycleEvent(session.meta.id, session.task, session.meta.todos ?? [], activity, nextTaskEventCursor()));
     };
     // Discovery file — the desktop shell reads this to find the running server (like a pid/port file).
     const discoveryDir = join(deps.discoveryHome ?? homedir(), ".hara");
@@ -448,13 +462,13 @@ export async function startServe(opts, deps) {
         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 event = taskLifecycleEvent(sessionId, s.task, todos, activity, nextTaskEventCursor());
+            const { at: _at, streamId: _streamId, sequence: _sequence, ...stableEvent } = event;
             const signature = JSON.stringify(stableEvent);
             if (signature === lastTaskStateSignature)
                 return;
             lastTaskStateSignature = signature;
-            broadcast("event.task_state", { ...event });
+            publishTaskState(event);
         };
         broadcast("event.turn_start", { sessionId, taskId: s.task.id, turnId: s.task.turnId });
         emitTaskState({ state: "running", phase: "starting" });

package/dist/serve/task-events.js

@@ -5,7 +5,14 @@ function bounded(value, max) {
 }
 /** 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()) {
+export function taskLifecycleEvent(sessionId, task, todos = [], activity, cursor, at = new Date().toISOString()) {
+    const streamId = cursor.streamId.trim();
+    if (!streamId || streamId.length > 128) {
+        throw new Error("task lifecycle streamId must contain 1-128 characters");
+    }
+    if (!Number.isSafeInteger(cursor.sequence) || cursor.sequence <= 0) {
+        throw new Error("task lifecycle sequence must be a positive safe integer");
+    }
     const current = todos.find((todo) => todo.status === "in_progress")
         ?? todos.find((todo) => todo.status === "pending");
     const detail = bounded(activity.detail, 500);
@@ -22,6 +29,8 @@ export function taskLifecycleEvent(sessionId, task, todos = [], activity, at = n
         : task.status;
     return {
         version: TASK_LIFECYCLE_EVENT_VERSION,
+        streamId,
+        sequence: cursor.sequence,
         sessionId,
         taskId: task.id,
         turnId: task.turnId,

package/package.json

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