@nanhara/hara 0.129.0 → 0.130.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.1 — 2026-07-21 — Windows private-state portability
+
+- `hara serve` no longer calls the inapplicable POSIX `fchmod` operation on Windows discovery
+  directory and file handles. Official Windows standalone builds can now create the authenticated
+  `serve.json` record instead of exiting with `EPERM`.
+- The same descriptor-mode boundary is shared by all private-state readers and writers: Windows
+  retains file type, identity, no-replace, atomic-write, and symlink/reparse-point checks while
+  omitting only POSIX owner bits; macOS and Linux still fail closed if permission tightening fails.
+- Upgrade with `npm i -g @nanhara/hara@0.130.1`.
+
+## 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/fs-permissions.js

@@ -0,0 +1,14 @@
+import { fchmodSync } from "node:fs";
+/**
+ * Tighten an already-verified descriptor on platforms that implement POSIX ownership modes.
+ *
+ * Windows Node/Bun may expose `fchmodSync`, but the underlying handle can reject it with EPERM and
+ * Windows ACLs do not implement these POSIX owner bits. Callers must retain their type, identity,
+ * no-replace, and atomic-write checks; only the inapplicable mode operation is omitted on Windows.
+ * POSIX errors deliberately propagate so a failed private-state repair remains fail-closed.
+ */
+export function tightenPrivateDescriptorMode(fd, mode, platform = process.platform, writeMode = fchmodSync) {
+    if (platform === "win32")
+        return;
+    writeMode(fd, mode);
+}

package/dist/security/private-state.js

@@ -1,12 +1,13 @@
 // Owner-only migration for Hara's local control plane. New writers should still create private files
 // directly, but this repairs installations created by older releases and makes ~/.hara non-traversable by
 // other local users before credentials/session state are read.
-import { closeSync, chmodSync, constants, fchmodSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, chmodSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { FileReadLimitError, MAX_EDIT_READ_BYTES, decodeUtf8Strict, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
+import { tightenPrivateDescriptorMode } from "../fs-permissions.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
 const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results", "plugin-receipts", "artifacts"]);
 const tightenedHomes = new Set();
@@ -81,7 +82,7 @@ function verifyAndTightenPrivateDirectory(path) {
             if (!opened.isDirectory() || opened.dev !== inspected.dev || opened.ino !== inspected.ino) {
                 throw new Error(`private Hara state directory changed while opening: '${path}'`);
             }
-            fchmodSync(fd, 0o700);
+            tightenPrivateDescriptorMode(fd, 0o700);
         }
         finally {
             closeSync(fd);
@@ -190,13 +191,7 @@ export function readPrivateStateFileSnapshotSync(path, maxBytes = MAX_EDIT_READ_
             rejectHardLinks: true,
             protectSensitive: false,
         });
-        try {
-            fchmodSync(fd, 0o600);
-        }
-        catch (error) {
-            if (process.platform !== "win32")
-                throw error;
-        }
+        tightenPrivateDescriptorMode(fd, 0o600);
         // chmod may update ctime; capture the authoritative baseline afterwards.
         info = fstatSync(fd);
         if (info.size > limit)
@@ -334,13 +329,7 @@ export function writePrivateStateBytesOnceSync(binding, bytes) {
     try {
         fd = openSync(temp, "wx", 0o600);
         writeFileSync(fd, bytes);
-        try {
-            fchmodSync(fd, 0o600);
-        }
-        catch (error) {
-            if (process.platform !== "win32")
-                throw error;
-        }
+        tightenPrivateDescriptorMode(fd, 0o600);
         fsyncSync(fd);
         const stagedInfo = fstatSync(fd);
         if (!stagedInfo.isFile() || stagedInfo.nlink !== 1) {
@@ -422,13 +411,7 @@ export function writePrivateStateFileSync(binding, text, options = {}) {
         // Bun's Windows numeric-open compatibility can otherwise turn this valid create into a false ENOENT.
         fd = openSync(temp, "wx", 0o600);
         writeFileSync(fd, text, "utf8");
-        try {
-            fchmodSync(fd, 0o600);
-        }
-        catch (error) {
-            if (process.platform !== "win32")
-                throw error;
-        }
+        tightenPrivateDescriptorMode(fd, 0o600);
         fsyncSync(fd);
         const stagedInfo = fstatSync(fd);
         if (!stagedInfo.isFile() || stagedInfo.nlink !== 1)

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

@@ -5,7 +5,7 @@
 // (no import cycle back into the CLI entry).
 import { WebSocketServer } from "ws";
 import { randomBytes, randomUUID, timingSafeEqual, createHash } from "node:crypto";
-import { closeSync, constants as fsConstants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, constants as fsConstants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, sep } from "node:path";
 import "../tools/all.js"; // register the full built-in toolset — serve must work as a standalone entry
@@ -32,9 +32,10 @@ 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 { tightenPrivateDescriptorMode } from "../fs-permissions.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
 import { redactSensitiveText, redactSensitiveValue } from "../security/secrets.js";
 import { ArtifactStoreError, commitArtifact, getArtifact, importArtifact, listArtifactRevisions, listArtifacts, revertArtifact, } from "../artifacts/store.js";
@@ -81,7 +82,7 @@ const ensurePrivateDiscoveryDir = (dir) => {
             throw new Error(`${dir} must be a private directory, not a symlink`);
         // mkdir's mode does not affect a legacy directory. Operate through the verified descriptor so a path
         // replacement cannot redirect chmod to a symlink target between validation and permission tightening.
-        fchmodSync(fd, 0o700);
+        tightenPrivateDescriptorMode(fd, 0o700);
     }
     finally {
         if (fd !== undefined)
@@ -173,7 +174,7 @@ const writeDiscovery = async (dir, path, record) => {
         let fd;
         try {
             fd = openSync(temp, "wx", 0o600);
-            fchmodSync(fd, 0o600);
+            tightenPrivateDescriptorMode(fd, 0o600);
             writeFileSync(fd, `${JSON.stringify(record, null, 2)}\n`, "utf8");
             fsyncSync(fd);
             closeSync(fd);
@@ -295,6 +296,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 +360,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 +463,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.1",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"