@nanhara/hara 0.124.0 → 0.124.2

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.124.2 — 2026-07-17 — reliable WeCom gateway transport
+
+- **The WeCom gateway is ready only after WeCom accepts its credentials.** Hara now waits for the
+  `aibot_subscribe` acknowledgement, stops after five bounded credential failures, monitors heartbeat
+  acknowledgements, reconnects half-open sockets with bounded exponential backoff, and stops cleanly when
+  `disconnected_event` reports that another active connection replaced it.
+- **A failed WeCom delivery is no longer reported as success.** Correlated requests reject on timeout,
+  cancellation, connection loss, malformed/nonzero acknowledgements, or missing upload results. Text and file
+  transfers have hard deadlines and credential-scoped per-chat FIFO ordering; chunk uploads retry within a
+  fixed bound, and transport diagnostics redact the configured Secret.
+- **WeCom callbacks now participate in Hara's cross-restart execution boundary.** Stable `msgid` and
+  `create_time` metadata feed stale-event filtering, deduplication, and cached no-rerun outcomes so a redelivery
+  cannot silently launch the same coding/file task again.
+- **Inbound media fails closed and keeps file types separate.** Images remain vision attachments, while files
+  and videos become explicit private local-path references. Invalid AES ciphertext/padding is rejected instead
+  of returning padded bytes, and unfinished handoffs remove adapter-owned temporary files.
+- A deterministic local WebSocket suite covers auth failure, heartbeat reconnection, request errors, strict
+  decryption, media classification, two-chunk upload, and a spawned `hara gateway --platform wecom` allowlist
+  round trip without using real enterprise credentials.
+- Upgrade with `npm i -g @nanhara/hara@0.124.2`.
+
+## 0.124.1 — 2026-07-16 — Windows native private-state and file-identity portability
+
+- **Windows private state works in both Node and the native Bun executable.** Exclusive staging creation now
+  uses the portable `wx`/`CREATE_NEW` contract instead of passing Bun numeric flags that could surface a false
+  `ENOENT`. Config, credentials, gateway state, discovery records, and other private atomic writers retain
+  create-if-absent publication, hard-link fencing, fsync, and fail-closed alias checks.
+- **Descriptor-to-path identity checks follow the host's real guarantees.** Windows Node may report a
+  volume-derived `dev` from `fstat` but `dev=0` from `lstat` for the exact same NTFS file. Hara now correlates
+  an already-open descriptor with its already-bounded path using the stable file id and link count, while
+  POSIX still requires device, inode, and owner-only mode. Arbitrary path-to-path protected-file detection
+  continues to require device + inode, so the portability fix does not weaken hard-link protection.
+- **The release gate now exercises the reported failure on a real Windows runtime.** CI installs the pinned
+  Bun 1.3.9 x64-baseline runtime, runs portable file-state contracts, compiles `hara.exe`, and executes the
+  hostile-cwd standalone smoke including an isolated `hara doctor`. Bounded failure annotations keep future
+  Windows-only regressions diagnosable without exposing credentials. Production dependency audits retry a
+  transient registry failure only within a fixed bound and still require a real successful audit result.
+- Windows users on 0.124.0 should upgrade with `npm i -g @nanhara/hara@0.124.1`; Desktop releases that bundle
+  a sidecar should pin this patch or newer.
+
 ## 0.124.0 — 2026-07-16 — task-safe interaction, bounded context, and private-state hardening
 
 - **Idle conversation no longer hijacks an unfinished task.** Ordinary input starts a new execution while

package/dist/cron/store.js

@@ -7,6 +7,8 @@ import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lsta
 import { cronMatches, parseCron, validTz } from "./schedule.js";
 import { compareProcessIdentity, defaultProcessIdentity } from "../process-identity.js";
 import { sleepSync } from "../sync-sleep.js";
+import { optionalPosixOpenFlag } from "../fs-open-flags.js";
+import { sameOpenedFileIdentity } from "../fs-identity.js";
 /** Hard persistence bounds: outages must apply backpressure instead of growing jobs.json forever. */
 export const MAX_CRON_PENDING_NOTIFICATIONS = 64;
 const CRON_RUN_NOTIFICATION_RESERVE = 2;
@@ -43,11 +45,10 @@ function readStoreLockSnapshot(path) {
         const before = lstatSync(path);
         let raw = null;
         if (before.isFile() && before.size <= MAX_STORE_LOCK_BYTES) {
-            const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-            const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+            const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
             try {
                 const opened = fstatSync(fd);
-                if (opened.isFile() && opened.dev === before.dev && opened.ino === before.ino && opened.size <= MAX_STORE_LOCK_BYTES) {
+                if (opened.isFile() && sameOpenedFileIdentity(opened, before) && opened.size <= MAX_STORE_LOCK_BYTES) {
                     const buffer = Buffer.alloc(opened.size);
                     let offset = 0;
                     while (offset < buffer.length) {

package/dist/fs-identity.js

@@ -0,0 +1,11 @@
+/**
+ * Correlate an already-open descriptor with a stat of the same bounded path. Node on Windows may report
+ * a volume-derived `dev` for fstat and `0` for lstat/stat of that exact NTFS file. Its file id (`ino`) stays
+ * stable, and the caller has already fixed the path/parent boundary, so requiring `dev` there rejects valid
+ * files without adding an identity fence. POSIX retains the ordinary device + inode comparison.
+ *
+ * Do not use this to decide whether two arbitrary Windows paths are hard links across unrelated roots.
+ */
+export function sameOpenedFileIdentity(left, right, platform = process.platform) {
+    return left.ino === right.ino && (platform === "win32" || left.dev === right.dev);
+}

package/dist/fs-open-flags.js

@@ -0,0 +1,14 @@
+import { constants } from "node:fs";
+/**
+ * Bun's Windows compatibility layer may expose POSIX-only fs constants even though CreateFileW cannot
+ * consume them. Node documents that Windows supports neither O_DIRECTORY, O_NOFOLLOW nor O_NONBLOCK;
+ * passing Bun's numeric values can turn an otherwise valid create/open into a misleading ENOENT.
+ *
+ * Windows callers retain their lstat/fstat/identity checks and O_CREAT|O_EXCL no-replace semantics.
+ */
+export function optionalPosixOpenFlag(name, platform = process.platform) {
+    if (platform === "win32")
+        return 0;
+    const value = constants[name];
+    return typeof value === "number" ? value : 0;
+}

package/dist/fs-read.js

@@ -4,6 +4,8 @@ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpat
 import { open } from "node:fs/promises";
 import { StringDecoder } from "node:string_decoder";
 import { sensitiveFileError } from "./security/sensitive-files.js";
+import { optionalPosixOpenFlag } from "./fs-open-flags.js";
+import { sameOpenedFileIdentity } from "./fs-identity.js";
 export class BinaryFileError extends Error {
     constructor(path) {
         super(`${path} appears to be binary (NUL byte detected)`);
@@ -100,10 +102,8 @@ export function verifyOpenedRegularFileSync(path, opened, options = {}) {
     const currentLink = lstatSync(path);
     const currentTarget = statSync(canonical);
     if (currentLink.isSymbolicLink()
-        || currentLink.dev !== opened.dev
-        || currentLink.ino !== opened.ino
-        || currentTarget.dev !== opened.dev
-        || currentTarget.ino !== opened.ino) {
+        || !sameOpenedFileIdentity(currentLink, opened)
+        || !sameOpenedFileIdentity(currentTarget, opened)) {
         throw new Error(`refusing to access ${path}: path changed while opening it`);
     }
     return canonical;
@@ -118,8 +118,7 @@ export async function openVerifiedRegularFileNoFollow(path, options = {}) {
     const before = lstatSync(path);
     if (before.isSymbolicLink())
         throw new NonRegularFileError(path);
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    const handle = await open(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
     try {
         const info = await handle.stat();
         const canonicalPath = verifyOpenedRegularFileSync(path, info, options);
@@ -189,8 +188,7 @@ export function readVerifiedRegularFileSnapshotSync(path, maxBytes = MAX_EDIT_RE
     const before = lstatSync(path);
     if (before.isSymbolicLink())
         throw new NonRegularFileError(path);
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
     try {
         const info = fstatSync(fd);
         verifyOpenedRegularFileSync(path, info, {
@@ -243,11 +241,10 @@ function withVerifiedContextFdSync(path, read) {
         throw new ProtectedContextFileError(denied);
     // O_NOFOLLOW is not exposed on every platform. The before/after lstat checks retain fail-closed symlink
     // behaviour there; on POSIX O_NOFOLLOW makes the critical open itself atomic.
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
     const before = lstatSync(path);
     if (before.isSymbolicLink())
         throw new NonRegularFileError(path);
-    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
     try {
         const info = fstatSync(fd);
         verifyOpenedRegularFileSync(path, info, {
@@ -387,12 +384,11 @@ async function readRegularFileSnapshotWithFlags(path, maxBytes, flags) {
     }
 }
 export async function readRegularFileSnapshot(path, maxBytes = MAX_EDIT_READ_BYTES) {
-    return readRegularFileSnapshotWithFlags(path, maxBytes, constants.O_RDONLY | constants.O_NONBLOCK);
+    return readRegularFileSnapshotWithFlags(path, maxBytes, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK"));
 }
 /** Quarantine/transaction reader: reject a symlink at open(2), then validate/read that same fd. */
 export async function readRegularFileSnapshotNoFollow(path, maxBytes = MAX_EDIT_READ_BYTES) {
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    return readRegularFileSnapshotWithFlags(path, maxBytes, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    return readRegularFileSnapshotWithFlags(path, maxBytes, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK") | optionalPosixOpenFlag("O_NOFOLLOW"));
 }
 export async function readRegularFileText(path, maxBytes = MAX_EDIT_READ_BYTES) {
     return (await readRegularFileSnapshot(path, maxBytes)).text;
@@ -402,7 +398,7 @@ export function readTextPrefixSync(path, maxChars) {
     const requested = Number.isFinite(maxChars) ? Math.floor(maxChars) : MAX_PREFIX_CHARS;
     const chars = Math.min(MAX_PREFIX_CHARS, Math.max(0, requested));
     // O_NONBLOCK makes opening a FIFO return immediately; fstat on this exact fd then rejects it before read.
-    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK"));
     try {
         const info = fstatSync(fd);
         if (!info.isFile())
@@ -504,7 +500,8 @@ export async function streamFileSlice(path, offset = 1, limit = 300, options = {
     const verified = options.protectSensitive
         ? await openVerifiedRegularFileNoFollow(path, { action: "read", rejectHardLinks: true, protectSensitive: true })
         : null;
-    const handle = verified?.handle ?? await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const handle = verified?.handle
+        ?? await open(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK"));
     let stream;
     try {
         const info = verified?.info ?? await handle.stat();

package/dist/fs-write.js

@@ -5,6 +5,8 @@ import { basename, dirname, join, resolve } from "node:path";
 import { constants, linkSync, lstatSync, readlinkSync, realpathSync, renameSync, symlinkSync, unlinkSync } from "node:fs";
 import { lstat, mkdir, open, realpath, rmdir, stat } from "node:fs/promises";
 import { NonRegularFileError, readRegularFileSnapshotNoFollow } from "./fs-read.js";
+import { optionalPosixOpenFlag } from "./fs-open-flags.js";
+import { sameOpenedFileIdentity } from "./fs-identity.js";
 import { canonicalizeProspectivePath, lexicalSensitiveFileReason, sensitiveFileError, } from "./security/sensitive-files.js";
 export class FileChangedError extends Error {
     code = "HARA_FILE_CHANGED";
@@ -296,7 +298,7 @@ async function syncDirectory(path) {
     try {
         // The directory name can be exchanged after rename. O_NONBLOCK plus fstat on this exact descriptor
         // keeps best-effort durability from hanging forever on a replacement FIFO/device.
-        const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        const handle = await open(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NONBLOCK"));
         try {
             if (!(await handle.stat()).isDirectory())
                 return;
@@ -508,8 +510,7 @@ export async function atomicWriteText(path, content, options = {}) {
                 verifyCommitParent();
                 const current = lstatSync(temp);
                 if (current.isFile()
-                    && current.dev === writtenIdentity.dev
-                    && current.ino === writtenIdentity.ino)
+                    && sameOpenedFileIdentity(current, writtenIdentity))
                     unlinkSync(temp);
             }
             catch {

package/dist/gateway/outbound-files.js

@@ -6,6 +6,8 @@ import { chmodSync, constants, lstatSync, mkdirSync, readdirSync, realpathSync,
 import { open } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync } from "../fs-read.js";
+import { optionalPosixOpenFlag } from "../fs-open-flags.js";
+import { sameOpenedFileIdentity } from "../fs-identity.js";
 export const OUTBOUND_FILE_MAX_BYTES = 20 * 1024 * 1024;
 export const OUTBOUND_BATCH_MAX_BYTES = 20 * 1024 * 1024;
 export const OUTBOUND_BATCH_MAX_FILES = 4;
@@ -90,17 +92,15 @@ async function appendOutbox(outbox, snapshot, signal) {
         if (error?.code !== "ENOENT")
             throw error;
     }
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    const handle = await open(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | noFollow, 0o600);
+    const handle = await open(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | optionalPosixOpenFlag("O_NOFOLLOW"), 0o600);
     try {
         const info = await handle.stat();
         const current = lstatSync(path);
         if (!info.isFile()
             || info.nlink > 1
             || current.isSymbolicLink()
-            || current.dev !== info.dev
-            || current.ino !== info.ino
-            || (before && (before.dev !== info.dev || before.ino !== info.ino))
+            || !sameOpenedFileIdentity(current, info)
+            || (before && !sameOpenedFileIdentity(before, info))
             || !ownedByProcess(path))
             throw new Error(`unsafe gateway outbox: ${outbox}`);
         await handle.chmod(0o600);
@@ -251,7 +251,7 @@ async function readOutbox(outbox) {
         await verified?.handle.close().catch(() => { });
         try {
             const current = lstatSync(resolve(outbox));
-            if (verified && !current.isSymbolicLink() && current.dev === verified.info.dev && current.ino === verified.info.ino) {
+            if (verified && !current.isSymbolicLink() && sameOpenedFileIdentity(current, verified.info)) {
                 unlinkSync(resolve(outbox));
             }
         }
@@ -380,8 +380,7 @@ export function cleanupOutboundSnapshot(path) {
             && entry.isFile()
             && !entry.isSymbolicLink()
             && entry.nlink === 1
-            && entry.dev === expected.dev
-            && entry.ino === expected.ino
+            && sameOpenedFileIdentity(entry, expected)
             && ownedByProcess(candidate))
             unlinkSync(candidate);
         if (readdirSync(dir).length === 0)

package/dist/gateway/runtime-state.js

@@ -13,6 +13,8 @@ import { atomicWriteText, bindHaraPrivateStateWritePath, FileChangedError } from
 import { ensurePrivateStateSubdirectory, readPrivateStateFileSnapshot, } from "../security/private-state.js";
 import { sleepSync } from "../sync-sleep.js";
 import { compareProcessIdentity, defaultProcessIdentity } from "../process-identity.js";
+import { optionalPosixOpenFlag } from "../fs-open-flags.js";
+import { sameOpenedFileIdentity } from "../fs-identity.js";
 const PLATFORM = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const LOCK_BYTES = 4 * 1024;
 const LOCK_WAIT_MS = 5_000;
@@ -100,13 +102,11 @@ function leaseStagingPath(path, record) {
     return `${path}.${record.pid}.${record.token}.pending`;
 }
 function readLease(path, platform) {
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    const nonBlock = typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0;
     let fd;
     try {
         // O_NONBLOCK is inert for regular files and prevents a hostile FIFO/device at the lock path from hanging
         // gateway startup before fstat can reject it.
-        fd = openSync(path, constants.O_RDONLY | noFollow | nonBlock);
+        fd = openSync(path, constants.O_RDONLY | optionalPosixOpenFlag("O_NOFOLLOW") | optionalPosixOpenFlag("O_NONBLOCK"));
     }
     catch (error) {
         if (errorCode(error) === "ENOENT")
@@ -175,8 +175,7 @@ function readLease(path, platform) {
         if (!staging.isFile()
             || staging.isSymbolicLink()
             || staging.nlink !== 2
-            || staging.dev !== info.dev
-            || staging.ino !== info.ino)
+            || !sameOpenedFileIdentity(staging, info))
             throw new Error(`refusing malformed gateway instance lock: ${path}`);
         return { record, dev: info.dev, ino: info.ino, stagingPath };
     }
@@ -187,8 +186,7 @@ function readLease(path, platform) {
 function sameLease(left, right) {
     return Boolean(left
         && right
-        && left.dev === right.dev
-        && left.ino === right.ino
+        && sameOpenedFileIdentity(left, right)
         && left.record.pid === right.record.pid
         && left.record.token === right.record.token);
 }
@@ -198,8 +196,7 @@ function unlinkLease(path, expected) {
         || current.isSymbolicLink()
         || current.nlink < 1
         || current.nlink > 2
-        || current.dev !== expected.dev
-        || current.ino !== expected.ino)
+        || !sameOpenedFileIdentity(current, expected))
         throw new Error(`gateway instance lock changed before removal: ${path}`);
     if (current.nlink === 2) {
         if (!expected.stagingPath)
@@ -208,30 +205,26 @@ function unlinkLease(path, expected) {
         if (!staging.isFile()
             || staging.isSymbolicLink()
             || staging.nlink !== 2
-            || staging.dev !== expected.dev
-            || staging.ino !== expected.ino)
+            || !sameOpenedFileIdentity(staging, expected))
             throw new Error(`gateway instance lock changed before removal: ${path}`);
         unlinkSync(expected.stagingPath);
         current = lstatSync(path);
         if (!current.isFile()
             || current.isSymbolicLink()
             || current.nlink !== 1
-            || current.dev !== expected.dev
-            || current.ino !== expected.ino)
+            || !sameOpenedFileIdentity(current, expected))
             throw new Error(`gateway instance lock changed before removal: ${path}`);
     }
     unlinkSync(path);
 }
 function writeLease(path, record) {
-    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    const nonBlock = typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0;
     const stagingPath = leaseStagingPath(path, record);
     let fd;
     let published = false;
     try {
         // Never expose an empty/partial owner record at the canonical path. The private staging inode is fully
         // written + fsynced first; link(2) then publishes it atomically and refuses to replace an existing owner.
-        fd = openSync(stagingPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow | nonBlock, 0o600);
+        fd = openSync(stagingPath, "wx", 0o600);
         writeFileSync(fd, JSON.stringify(record), "utf8");
         fsyncSync(fd);
         closeSync(fd);
@@ -853,8 +846,7 @@ export class GatewayFlowRunStore {
         if (!current.isFile()
             || current.isSymbolicLink()
             || current.nlink !== 1
-            || current.dev !== snapshot.dev
-            || current.ino !== snapshot.ino)
+            || !sameOpenedFileIdentity(current, snapshot))
             throw new Error(`gateway flow run changed before removal: ${path}`);
         unlinkSync(path);
     }
@@ -1172,8 +1164,7 @@ export class GatewayRunOutcomeStore {
         if (!current.isFile()
             || current.isSymbolicLink()
             || current.nlink !== 1
-            || current.dev !== snapshot.dev
-            || current.ino !== snapshot.ino)
+            || !sameOpenedFileIdentity(current, snapshot))
             throw new Error(`gateway run outcome changed before removal: ${path}`);
         unlinkSync(path);
     }