@nanhara/hara 0.121.1 → 0.122.1

package/dist/session/store.js

@@ -22,11 +22,91 @@ export function automatedTitle(source, sourceName, at = new Date()) {
 function sessionsDir() {
     const d = join(homedir(), ".hara", "sessions");
     mkdirSync(d, { recursive: true, mode: 0o700 });
-    chmodSync(d, 0o700); // tighten legacy installs too; session transcripts are private
+    // `mode` is ignored when the directory already exists. Tighten legacy installs too: a session holds
+    // private conversation history, so inheriting a permissive umask (typically 0755) is not acceptable.
+    chmodSync(d, 0o700);
     return d;
 }
-const sessionFile = (id) => join(sessionsDir(), `${id}.json`);
-const lockFile = (id) => join(sessionsDir(), `${id}.lock`);
+/** Session ids become filenames. Gateway/platform ids are not always UUIDs, so allow printable filename
+ * characters broadly while rejecting separators, traversal sentinels, NULs, and unbounded names. */
+export function validSessionId(id) {
+    return typeof id === "string" && id.length > 0 && id.length <= 220 && id !== "." && id !== ".." && !/[\\/\0]/.test(id);
+}
+function checkedSessionId(id) {
+    if (!validSessionId(id))
+        throw new Error("invalid session id");
+    return id;
+}
+const sessionFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.json`);
+const lockFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.lock`);
+const reclaimFile = (id) => join(sessionsDir(), `${checkedSessionId(id)}.lock.reclaim`);
+/** Distinguish a missing session from an existing but unreadable/corrupt one without exposing its path. */
+export function sessionFileExists(id) {
+    if (!validSessionId(id))
+        return false;
+    return existsSync(sessionFile(id));
+}
+// A pid alone is not ownership: pids are reused, and another writer could replace a lock between read and
+// release. Keep the random token for every lock this module actually created and require both on release.
+const ownedLocks = new Map();
+function readLockRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!Number.isInteger(parsed.pid) ||
+            Number(parsed.pid) <= 0 ||
+            typeof parsed.startedAt !== "number" ||
+            (parsed.token !== undefined && (typeof parsed.token !== "string" || !parsed.token))) {
+            return null;
+        }
+        return { pid: Number(parsed.pid), startedAt: parsed.startedAt, ...(parsed.token ? { token: parsed.token } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Create one private file without ever replacing an existing path. On a partial write, remove only the
+ *  inode we just created. Callers use this for both the primary lock and the stale-lock reclaimer. */
+function writeExclusive(path, record) {
+    let fd;
+    try {
+        fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(record), "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+                fd = undefined;
+            }
+            catch {
+                /* continue with best-effort removal */
+            }
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                /* the original error is more useful */
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* the acquisition will fail closed */
+            }
+        }
+    }
+}
+function newLockRecord() {
+    return { pid: process.pid, startedAt: Date.now(), token: randomUUID() };
+}
 /** Is a process with this pid alive? `process.kill(pid, 0)` sends no signal — it just probes: throws
  *  ESRCH if dead, EPERM if alive-but-not-ours (still alive). Best-effort across platforms. */
 function pidAlive(pid) {
@@ -38,60 +118,145 @@ function pidAlive(pid) {
         return e?.code === "EPERM";
     }
 }
-/** Take an exclusive lock on a session so two hara processes can't resume the SAME session and corrupt
- *  its append-only history by racing writes. Returns `{ ok: true }` if acquired (or the previous holder
- *  is dead → we take over), or `{ ok: false, pid }` if a LIVE process already holds it. Best-effort: any
- *  filesystem hiccup resolves to `ok:true` so a lock problem never blocks the user. Pair with
- *  `releaseSessionLock` on exit. */
+/** Take an O_EXCL lock on a session so two hara processes cannot both pass a check-then-write race.
+ *  Filesystem/malformed-lock errors fail CLOSED. A well-formed dead holder can be reclaimed under a second
+ *  O_EXCL guard; a corrupt lock is deliberately left for explicit operator inspection/removal. */
 export function acquireSessionLock(id) {
-    const f = lockFile(id);
+    let f;
+    let reclaim;
     try {
-        if (existsSync(f)) {
-            const held = JSON.parse(readFileSync(f, "utf8"));
-            if (typeof held.pid === "number" && held.pid !== process.pid && pidAlive(held.pid)) {
-                return { ok: false, pid: held.pid };
-            }
-            // stale (dead pid) or already ours → fall through and (re)claim it
+        f = lockFile(id);
+        reclaim = reclaimFile(id);
+    }
+    catch {
+        return { ok: false };
+    }
+    // A stale-lock recovery is changing the primary lock. New contenders wait/fail instead of creating a
+    // primary lock in the short remove→create window.
+    if (existsSync(reclaim)) {
+        const stale = readLockRecord(reclaim);
+        if (!stale?.token || !Number.isFinite(stale.startedAt) || stale.startedAt <= 0 || pidAlive(stale.pid)) {
+            return { ok: false, pid: readLockRecord(f)?.pid };
         }
-        writeFileSync(f, JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
+        const current = readLockRecord(reclaim);
+        if (!current?.token ||
+            current.pid !== stale.pid ||
+            current.token !== stale.token ||
+            current.startedAt !== stale.startedAt ||
+            pidAlive(current.pid)) {
+            return { ok: false, pid: readLockRecord(f)?.pid };
+        }
+        try {
+            rmSync(reclaim);
+        }
+        catch {
+            return { ok: false, pid: readLockRecord(f)?.pid };
+        }
+    }
+    const claim = newLockRecord();
+    try {
+        writeExclusive(f, claim);
+        ownedLocks.set(id, claim.token);
         return { ok: true };
     }
+    catch (error) {
+        if (error?.code !== "EEXIST")
+            return { ok: false };
+    }
+    const held = readLockRecord(f);
+    if (!held)
+        return { ok: false }; // malformed/unreadable is not proof that the owner is dead
+    if (held.pid === process.pid && !!held.token && ownedLocks.get(id) === held.token)
+        return { ok: true }; // re-entrant
+    if (pidAlive(held.pid))
+        return { ok: false, pid: held.pid };
+    // Serialize stale takeover. All participants check this guard before attempting the primary O_EXCL create,
+    // so no second contender can steal the freshly-created primary lock during reclamation.
+    const reclaimClaim = newLockRecord();
+    try {
+        writeExclusive(reclaim, reclaimClaim);
+    }
     catch {
+        return { ok: false, pid: held.pid };
+    }
+    try {
+        const current = readLockRecord(f);
+        if (!current)
+            return { ok: false }; // disappeared/corrupted unexpectedly: fail closed
+        if (current.pid === process.pid && !!current.token && ownedLocks.get(id) === current.token)
+            return { ok: true };
+        if (pidAlive(current.pid))
+            return { ok: false, pid: current.pid };
+        rmSync(f); // known-dead, well-formed owner; protected by the reclaim guard
+        const replacement = newLockRecord();
+        writeExclusive(f, replacement);
+        ownedLocks.set(id, replacement.token);
         return { ok: true };
     }
+    catch {
+        return { ok: false };
+    }
+    finally {
+        // Only remove our own reclaimer. A replacement would indicate outside interference and must survive.
+        const currentReclaim = readLockRecord(reclaim);
+        if (currentReclaim?.pid === process.pid && currentReclaim.token === reclaimClaim.token) {
+            try {
+                rmSync(reclaim);
+            }
+            catch {
+                /* fail closed on the next acquisition until this guard can be inspected/removed */
+            }
+        }
+    }
 }
 /** Release a session lock we hold (only removes it if the pid matches ours — never steals another's). */
 export function releaseSessionLock(id) {
+    const token = ownedLocks.get(id);
+    if (!token)
+        return;
     try {
         const f = lockFile(id);
-        if (!existsSync(f))
-            return;
-        const held = JSON.parse(readFileSync(f, "utf8"));
-        if (held?.pid === process.pid)
+        const held = readLockRecord(f);
+        if (held?.pid === process.pid && held.token === token)
             rmSync(f);
+        ownedLocks.delete(id);
     }
     catch {
-        /* best-effort */
+        // Keep the ownership token so a later cleanup attempt can still prove ownership. Never unlink blindly.
     }
 }
 /** Permanently delete a session from disk (codex thread/delete — unlike archive, irreversible).
  *  Refuses when a LIVE other process holds the lock; removes the session file and any lock we may hold.
  *  Returns false when the session doesn't exist or is held elsewhere. */
 export function deleteSession(id) {
-    const f = sessionFile(id);
+    let f;
+    try {
+        f = sessionFile(id);
+    }
+    catch {
+        return false;
+    }
     if (!existsSync(f))
         return false;
+    const ownedBefore = ownedLocks.has(id);
     const lock = acquireSessionLock(id);
     if (!lock.ok)
         return false;
+    let deleted = false;
     try {
         rmSync(f);
-        rmSync(lockFile(id), { force: true });
+        deleted = true;
         return true;
     }
     catch {
         return false;
     }
+    finally {
+        // A successful delete ends the session. On failure, release only a lock acquired by this call; a live
+        // SessionHub that already owned the lock must retain it and remain protected.
+        if (deleted || !ownedBefore)
+            releaseSessionLock(id);
+    }
 }
 /** A full UUID per session (the stable identity). */
 export const newSessionId = () => randomUUID();
@@ -99,10 +264,12 @@ export const newSessionId = () => randomUUID();
 export const shortId = (id) => id.slice(0, 8);
 /** Resolve a full id OR a unique prefix (e.g. the short id) to a session id, for `--resume`. */
 export function resolveSessionId(idOrPrefix) {
+    if (!validSessionId(idOrPrefix))
+        return null;
     if (existsSync(sessionFile(idOrPrefix)))
         return idOrPrefix;
-    const hit = listSessions().find((m) => m.id.startsWith(idOrPrefix));
-    return hit ? hit.id : null;
+    const hits = listSessions().filter((m) => m.id.startsWith(idOrPrefix));
+    return hits.length === 1 ? hits[0].id : null;
 }
 const STOP = new Set("the a an to of for and or with in on at my our your this that it is please can could you help me we add fix make do run create update change implement".split(" "));
 const WORDS = "amber basalt cedar delta ember flint grove harbor indigo jade kelp larch maple onyx quartz river slate terra umber vale willow zephyr".split(" ");
@@ -156,19 +323,34 @@ export function slugify(text, max = 40) {
         .slice(0, max)
         .replace(/-+$/, "");
 }
-export function saveSession(meta, history) {
-    meta.updatedAt = new Date().toISOString();
-    const data = { meta, history };
+/** Redact a deep in-memory copy while retaining fields that define session identity/routing. */
+function redactedSessionCopy(data) {
     // Redact a deep COPY: the live turn may still need a credential the user supplied, but the durable
     // transcript never should. Tool inputs/results are included, not just user message content.
     const safe = redactSensitiveValue(data).value;
-    // Keep structural routing/identity fields stable even if a path/model happens to resemble a secret.
-    safe.meta.id = meta.id;
-    safe.meta.cwd = meta.cwd;
-    safe.meta.provider = meta.provider;
-    safe.meta.model = meta.model;
-    safe.meta.createdAt = meta.createdAt;
-    safe.meta.updatedAt = meta.updatedAt;
+    // Structural routing/identity fields must remain byte-for-byte stable even if a path happens to contain
+    // credential-looking text. Free-form meta (title, workingSet, todos, sourceName) and ALL history remain
+    // deeply redacted. The live objects are not modified by the redaction walk.
+    safe.meta.id = data.meta.id;
+    safe.meta.cwd = data.meta.cwd;
+    safe.meta.provider = data.meta.provider;
+    safe.meta.model = data.meta.model;
+    safe.meta.createdAt = data.meta.createdAt;
+    safe.meta.updatedAt = data.meta.updatedAt;
+    if (data.meta.source !== undefined)
+        safe.meta.source = data.meta.source;
+    if (data.meta.effort !== undefined)
+        safe.meta.effort = data.meta.effort;
+    if (data.meta.archived !== undefined)
+        safe.meta.archived = data.meta.archived;
+    if (data.meta.gatewayOwner !== undefined)
+        safe.meta.gatewayOwner = data.meta.gatewayOwner;
+    return safe;
+}
+export function saveSession(meta, history) {
+    checkedSessionId(meta.id);
+    meta.updatedAt = new Date().toISOString();
+    const safe = redactedSessionCopy({ meta, history });
     const target = sessionFile(meta.id);
     const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
     let fd;
@@ -178,7 +360,8 @@ export function saveSession(meta, history) {
         fsyncSync(fd);
         closeSync(fd);
         fd = undefined;
-        renameSync(tmp, target); // same filesystem: readers see the complete old or complete new JSON
+        // Same directory/filesystem: readers observe the complete old JSON or complete new JSON, never a prefix.
+        renameSync(tmp, target);
         chmodSync(target, 0o600);
     }
     catch (error) {
@@ -199,29 +382,97 @@ export function saveSession(meta, history) {
         throw error;
     }
 }
-/** True if a parsed object has the SessionData shape we can safely use (meta object + history array). */
+function isTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isPersistedTodo(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const todo = value;
+    return (typeof todo.text === "string" &&
+        (todo.status === "pending" || todo.status === "in_progress" || todo.status === "done") &&
+        (todo.activeForm === undefined || typeof todo.activeForm === "string") &&
+        (todo.blockedBy === undefined || isStringArray(todo.blockedBy)) &&
+        (todo.owner === undefined || typeof todo.owner === "string"));
+}
+function isNeutralMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const message = value;
+    if (message.role === "user") {
+        return typeof message.content === "string" && (message.images === undefined || (Array.isArray(message.images) && message.images.every((image) => {
+            if (!image || typeof image !== "object" || Array.isArray(image))
+                return false;
+            const attachment = image;
+            return typeof attachment.path === "string" && typeof attachment.mediaType === "string";
+        })));
+    }
+    if (message.role === "assistant") {
+        return typeof message.text === "string" && Array.isArray(message.toolUses) && message.toolUses.every((use) => {
+            if (!use || typeof use !== "object" || Array.isArray(use))
+                return false;
+            const tool = use;
+            return typeof tool.id === "string" && typeof tool.name === "string" && Object.hasOwn(tool, "input");
+        });
+    }
+    if (message.role === "tool") {
+        return Array.isArray(message.results) && message.results.every((result) => {
+            if (!result || typeof result !== "object" || Array.isArray(result))
+                return false;
+            const tool = result;
+            return typeof tool.id === "string" && typeof tool.name === "string" && typeof tool.content === "string" &&
+                (tool.isError === undefined || typeof tool.isError === "boolean");
+        });
+    }
+    return false;
+}
+function isSessionMeta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const meta = value;
+    return (validSessionId(meta.id) &&
+        typeof meta.cwd === "string" &&
+        typeof meta.provider === "string" &&
+        typeof meta.model === "string" &&
+        typeof meta.title === "string" &&
+        isTimestamp(meta.createdAt) &&
+        isTimestamp(meta.updatedAt) &&
+        (meta.workingSet === undefined || isStringArray(meta.workingSet)) &&
+        (meta.todos === undefined || (Array.isArray(meta.todos) && meta.todos.every(isPersistedTodo))) &&
+        (meta.source === undefined || meta.source === "interactive" || meta.source === "gateway" || meta.source === "cron") &&
+        (meta.sourceName === undefined || typeof meta.sourceName === "string") &&
+        (meta.effort === undefined || typeof meta.effort === "string") &&
+        (meta.archived === undefined || typeof meta.archived === "boolean") &&
+        (meta.gatewayOwner === undefined || typeof meta.gatewayOwner === "string"));
+}
+/** True if a parsed object has the SessionData shape we can safely use. */
 function isSessionData(d) {
     const o = d;
-    return !!o && typeof o === "object" && !!o.meta && typeof o.meta === "object" && Array.isArray(o.history);
+    return !!o && typeof o === "object" && !Array.isArray(o) && isSessionMeta(o.meta) &&
+        Array.isArray(o.history) && o.history.every(isNeutralMessage);
 }
-/** Parse a legacy session and redact the in-memory copy. Reads stay read-only (no unlocked migration race);
- *  the next explicit save atomically replaces the old file with its private, redacted form. */
+/** Read only. Legacy plaintext is redacted in the returned in-memory copy but intentionally not migrated
+ *  here: listing/resuming must not perform an unlocked write. The next explicit save atomically migrates it. */
 function readSessionFile(p) {
     try {
         const d = JSON.parse(readFileSync(p, "utf8"));
-        if (!isSessionData(d))
-            return null;
-        return redactSensitiveValue(d).value;
+        return isSessionData(d) ? redactedSessionCopy(d) : null;
     }
     catch {
         return null;
     }
 }
 export function loadSession(id) {
+    if (!validSessionId(id))
+        return null;
     const p = sessionFile(id);
     if (!existsSync(p))
         return null;
-    return readSessionFile(p); // a corrupt / hand-edited file resumes as "no session" instead of crashing
+    const data = readSessionFile(p);
+    return data?.meta.id === id ? data : null; // a corrupt, spoofed, or hand-edited file resumes as "no session"
 }
 /** Session metas, newest first; optionally filtered to a cwd. */
 export function listSessions(cwd) {
@@ -230,12 +481,12 @@ export function listSessions(cwd) {
         if (!f.endsWith(".json"))
             continue;
         const d = readSessionFile(join(sessionsDir(), f));
-        if (d?.meta.id && d.meta.updatedAt)
-            metas.push(d.meta); // skip metaless/corrupt; never mutate while listing
+        if (d?.meta.id && validSessionId(d.meta.id) && f === `${d.meta.id}.json` && d.meta.updatedAt)
+            metas.push(d.meta); // skip spoofed/metalless/corrupt; never mutate while listing
     }
     if (cwd)
         metas = metas.filter((m) => m.cwd === cwd);
-    return metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return metas.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
 }
 export function latestForCwd(cwd) {
     const [m] = listSessions(cwd);

package/dist/skills/skills.js

@@ -2,12 +2,15 @@
 // ~/.hara/skills). Frontmatter: name, description (required) + when_to_use / allowed-tools /
 // context inline|fork / model / paths / user-invocable / disable-model-invocation. The body is the
 // instructions, loaded ON DEMAND (progressive disclosure) — only the frontmatter index sits in context.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { findProjectRoot } from "../context/agents-md.js";
 import { scanMemory } from "../memory/guard.js";
 import { pluginSkillDirs } from "../plugins/plugins.js";
+import { readModelContextFileSync, readVerifiedRegularFileSnapshot } from "../fs-read.js";
+import { atomicWriteText, bindAtomicWritePath } from "../fs-write.js";
+const MAX_SKILL_BYTES = 512 * 1024;
 export function skillsDir(cwd) {
     return join(findProjectRoot(cwd), ".hara", "skills");
 }
@@ -60,7 +63,7 @@ export function loadSkillIndex(cwd) {
             if (!existsSync(file))
                 continue;
             try {
-                const { fm } = parseFrontmatter(readFileSync(file, "utf8"));
+                const { fm } = parseFrontmatter(readModelContextFileSync(file, MAX_SKILL_BYTES));
                 const id = fm.name || entry;
                 byId.set(id, {
                     id,
@@ -86,7 +89,7 @@ export function loadSkillIndex(cwd) {
 /** Read a skill's instruction body (progressive disclosure — only when the model/user opens it). */
 export function loadSkillBody(skill) {
     try {
-        return parseFrontmatter(readFileSync(skill.file, "utf8")).body;
+        return parseFrontmatter(readModelContextFileSync(skill.file, MAX_SKILL_BYTES)).body;
     }
     catch {
         return "";
@@ -129,13 +132,19 @@ when_to_use: after editing code, before declaring a task done
 4. Summarize: what you ran, pass/fail, and anything still unverified.
 `;
 /** Create ~/.hara/skills/verify-change/SKILL.md as a starter example. Returns the paths written. */
-export function scaffoldSkills(cwd) {
+export async function scaffoldSkills(cwd) {
     const dir = join(skillsDir(cwd), "verify-change");
-    mkdirSync(dir, { recursive: true });
     const p = join(dir, "SKILL.md");
-    if (existsSync(p))
+    const boundary = bindAtomicWritePath(p, "scaffold skill");
+    try {
+        await readVerifiedRegularFileSnapshot(boundary.target, undefined, "scaffold skill");
         return [];
-    writeFileSync(p, SCAFFOLD, "utf8");
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    await atomicWriteText(boundary.target, SCAFFOLD, { expected: null, boundary });
     invalidateSkillsCache();
     return [p];
 }

package/dist/tools/all.js

@@ -12,6 +12,7 @@ import "./memory.js"; // memory_search/get/write/forget + skill_create
 import "./skill.js"; // skill loader
 import "./codebase.js"; // codebase_search
 import "./todo.js"; // todo_write
+import "./task.js"; // task (project-level persistent task pool)
 import "./send.js"; // send_file (self-gates on HARA_GATEWAY)
 import "./external_agent.js"; // external_agent (claude-code / codex delegation)
 import "./ask_user.js"; // ask_user