@nanhara/hara 0.121.1 → 0.122.0

package/dist/agent/structured.js

@@ -0,0 +1,231 @@
+/**
+ * Supported validation keywords are deliberately small and explicit:
+ * - `type`: object, array, string, number, integer, boolean, null (or a union array)
+ * - `required`, `properties`, and boolean `additionalProperties` for objects
+ * - one schema in `items` for arrays (tuple schemas are not supported)
+ * - `enum` containing JSON primitive values
+ * - annotation-only `title` and `description`
+ *
+ * Every other JSON-Schema keyword is rejected. In particular, combinators and references such as
+ * `$ref`, `allOf`, `anyOf`, `oneOf`, and `not` must never be silently accepted: doing so would make
+ * the CLI promise a constraint that this dependency-free validator did not enforce.
+ */
+const SUPPORTED_SCHEMA_KEYWORDS = new Set([
+    "type",
+    "required",
+    "properties",
+    "additionalProperties",
+    "items",
+    "enum",
+    "title",
+    "description",
+]);
+const SUPPORTED_SCHEMA_TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+function isSchemaObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function own(schema, key) {
+    return Object.hasOwn(schema, key) ? schema[key] : undefined;
+}
+function schemaTypes(schema) {
+    const type = own(schema, "type");
+    return type === undefined ? [] : Array.isArray(type) ? type : [type];
+}
+function describeSchemaValue(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function validateSchemaDefinition(schema, path = "$schema") {
+    if (!isSchemaObject(schema))
+        return `${path}: schema must be a plain JSON object`;
+    for (const keyword of Object.keys(schema)) {
+        if (!SUPPORTED_SCHEMA_KEYWORDS.has(keyword))
+            return `${path}.${keyword}: unsupported JSON-Schema keyword`;
+    }
+    const type = own(schema, "type");
+    if (type !== undefined) {
+        const types = Array.isArray(type) ? type : [type];
+        if (types.length === 0)
+            return `${path}.type: type array must not be empty`;
+        const seen = new Set();
+        for (const candidate of types) {
+            if (typeof candidate !== "string" || !SUPPORTED_SCHEMA_TYPES.has(candidate)) {
+                return `${path}.type: unsupported JSON-Schema type ${describeSchemaValue(candidate)}`;
+            }
+            if (seen.has(candidate))
+                return `${path}.type: duplicate type ${describeSchemaValue(candidate)}`;
+            seen.add(candidate);
+        }
+    }
+    for (const annotation of ["title", "description"]) {
+        const value = own(schema, annotation);
+        if (value !== undefined && typeof value !== "string")
+            return `${path}.${annotation}: expected string`;
+    }
+    const enumValues = own(schema, "enum");
+    if (enumValues !== undefined) {
+        if (!Array.isArray(enumValues) || enumValues.length === 0)
+            return `${path}.enum: expected a non-empty array`;
+        for (const value of enumValues) {
+            if (value !== null && !["string", "number", "boolean"].includes(typeof value)) {
+                return `${path}.enum: only JSON primitive values are supported`;
+            }
+            if (typeof value === "number" && !Number.isFinite(value))
+                return `${path}.enum: numbers must be finite`;
+        }
+    }
+    const required = own(schema, "required");
+    if (required !== undefined) {
+        if (!Array.isArray(required) || required.some((key) => typeof key !== "string")) {
+            return `${path}.required: expected an array of property names`;
+        }
+        if (new Set(required).size !== required.length)
+            return `${path}.required: property names must be unique`;
+    }
+    const properties = own(schema, "properties");
+    if (properties !== undefined) {
+        if (!isSchemaObject(properties))
+            return `${path}.properties: expected an object of property schemas`;
+        for (const [key, child] of Object.entries(properties)) {
+            const error = validateSchemaDefinition(child, `${path}.properties.${key}`);
+            if (error)
+                return error;
+        }
+    }
+    const additionalProperties = own(schema, "additionalProperties");
+    if (additionalProperties !== undefined && typeof additionalProperties !== "boolean") {
+        return `${path}.additionalProperties: only boolean values are supported`;
+    }
+    const items = own(schema, "items");
+    if (items !== undefined) {
+        const error = validateSchemaDefinition(items, `${path}.items`);
+        if (error)
+            return error;
+    }
+    const types = schemaTypes(schema);
+    const hasObjectKeyword = required !== undefined || properties !== undefined || additionalProperties !== undefined;
+    if (hasObjectKeyword && !types.includes("object")) {
+        return `${path}: object keywords require type "object"`;
+    }
+    if (items !== undefined && !types.includes("array"))
+        return `${path}: items requires type "array"`;
+    return null;
+}
+function actualType(value) {
+    return Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+}
+function matchesType(value, type) {
+    const actual = actualType(value);
+    if (type === "integer")
+        return actual === "number" && Number.isFinite(value) && Number.isInteger(value);
+    if (type === "number")
+        return actual === "number" && Number.isFinite(value);
+    return type === actual;
+}
+function validateValue(value, schema, path) {
+    const types = schemaTypes(schema);
+    if (types.length && !types.some((type) => matchesType(value, type))) {
+        return `${path}: expected ${types.join("|")}, got ${actualType(value)}`;
+    }
+    const enumValues = own(schema, "enum");
+    if (enumValues && !enumValues.some((candidate) => candidate === value)) {
+        return `${path}: value not in enum ${JSON.stringify(enumValues)}`;
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value) && types.includes("object")) {
+        const object = value;
+        const required = own(schema, "required");
+        for (const key of required ?? []) {
+            if (!Object.hasOwn(object, key))
+                return `${path}.${key}: required property missing`;
+        }
+        const properties = own(schema, "properties");
+        for (const [key, child] of Object.entries(properties ?? {})) {
+            if (Object.hasOwn(object, key)) {
+                const error = validateValue(object[key], child, `${path}.${key}`);
+                if (error)
+                    return error;
+            }
+        }
+        if (own(schema, "additionalProperties") === false) {
+            for (const key of Object.keys(object)) {
+                if (!properties || !Object.hasOwn(properties, key))
+                    return `${path}.${key}: unexpected property`;
+            }
+        }
+    }
+    if (Array.isArray(value) && types.includes("array")) {
+        const items = own(schema, "items");
+        if (items) {
+            for (let index = 0; index < value.length; index++) {
+                const error = validateValue(value[index], items, `${path}[${index}]`);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    return null;
+}
+/** Validate `value` against the supported JSON-Schema subset. Returns null when valid, otherwise a path-rich
+ * error. Invalid or unsupported schemas are errors too; they are never treated as permissive schemas. */
+export function validateAgainstSchema(value, schema, path = "$") {
+    const schemaError = validateSchemaDefinition(schema);
+    if (schemaError)
+        return `invalid schema — ${schemaError}`;
+    return validateValue(value, schema, path);
+}
+/** Parse a `--schema` CLI value: inline JSON, or (by the caller) file contents. Returns the schema object or
+ *  an error string. Top level must be an object schema — tool arguments are always a JSON object. */
+export function parseSchemaArg(raw) {
+    let schema;
+    try {
+        schema = JSON.parse(raw);
+    }
+    catch (e) {
+        return { error: `--schema is not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!isSchemaObject(schema))
+        return { error: "--schema must be a JSON object (a JSON-Schema)" };
+    let normalized = schema;
+    if (!Object.hasOwn(normalized, "type"))
+        normalized = { ...normalized, type: "object" };
+    if (own(normalized, "type") !== "object") {
+        return { error: "--schema top level must have type:'object' (tool args are an object)" };
+    }
+    if (!Object.hasOwn(normalized, "properties"))
+        normalized = { ...normalized, properties: {} };
+    const schemaError = validateSchemaDefinition(normalized);
+    if (schemaError)
+        return { error: `--schema is unsupported or invalid: ${schemaError}` };
+    return normalized;
+}
+/** The instruction appended to the prompt so the model knows the contract. */
+export const STRUCTURED_INSTRUCTION = "\n\nWhen you have the final answer, you MUST call the `structured_output` tool exactly once with the result " +
+    "matching its schema. Do not print the result as text — the tool call IS the answer.";
+/** The retry nudge when a turn ends without the tool having been called. */
+export const STRUCTURED_NUDGE = "You finished without calling `structured_output`. Call it NOW with your final result matching the schema — the tool call is the only accepted answer.";
+/** Build the run-scoped structured_output tool. `sink` receives the validated payload (last call wins). */
+export function structuredOutputTool(schema, sink) {
+    const schemaError = validateSchemaDefinition(schema);
+    if (schemaError)
+        throw new Error(`Invalid structured-output schema: ${schemaError}`);
+    return {
+        name: "structured_output",
+        description: "Record the final structured result of this task. Call exactly once, when done, with the complete answer.",
+        input_schema: schema,
+        kind: "read", // never prompts; the payload is data, not an action
+        async run(input) {
+            const err = validateAgainstSchema(input, schema);
+            if (err)
+                return `schema validation failed — ${err}. Fix the payload and call structured_output again.`;
+            sink(input);
+            return "structured result recorded.";
+        },
+    };
+}

package/dist/agent/touched.js

@@ -2,17 +2,31 @@
 // The loop records every file the MAIN conversation reads/edits; when the history is compacted to a
 // summary, the top-N most-recent files get their CURRENT on-disk content re-attached — so the model
 // doesn't lose the very files it was working on and re-read them all next turn.
-const touched = new Map(); // absolute path → last-touch timestamp
-export function recordTouch(path) {
+const DEFAULT_SCOPE = "default";
+const touchedByScope = new Map(); // scope → absolute path → last-touch timestamp
+function scopedTouched(scope) {
+    const key = scope?.trim() || DEFAULT_SCOPE;
+    const touched = touchedByScope.get(key) ?? new Map();
+    touchedByScope.set(key, touched);
+    return touched;
+}
+export function recordTouch(path, scope) {
+    const touched = scopedTouched(scope);
+    touched.delete(path);
     touched.set(path, Date.now());
+    if (touched.size > 200)
+        touched.delete(touched.keys().next().value);
 }
 /** Most-recently-touched first. */
-export function recentTouched(n = 5) {
-    return [...touched.entries()]
+export function recentTouched(n = 5, scope) {
+    return [...scopedTouched(scope).entries()]
         .sort((a, b) => b[1] - a[1])
         .slice(0, n)
         .map(([p]) => p);
 }
-export function clearTouched() {
-    touched.clear();
+export function clearTouched(scope) {
+    if (scope)
+        touchedByScope.delete(scope.trim() || DEFAULT_SCOPE);
+    else
+        touchedByScope.clear();
 }

package/dist/config.js

@@ -38,18 +38,27 @@ const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "p
 export function configPath() {
     return join(homedir(), ".hara", "config.json");
 }
+function configRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 export function readRawConfig() {
     const p = configPath();
     if (!existsSync(p))
         return {};
     try {
-        return JSON.parse(readFileSync(p, "utf8"));
+        return configRecord(JSON.parse(readFileSync(p, "utf8")));
     }
     catch {
         return {};
     }
 }
-const ROUTING_CONFIG_KEYS = new Set(["provider", "apiKey", "model", "baseURL"]);
+const ROUTING_CONFIG_KEYS = new Set([
+    "provider", "apiKey", "model", "baseURL",
+    "fallbackProvider", "fallbackApiKey", "fallbackModel", "fallbackBaseURL",
+    "visionApiKey", "visionModel", "visionBaseURL",
+    "embedProvider", "embedApiKey", "embedModel", "embedBaseURL",
+    "routeApiKey", "routeModel", "routeBaseURL",
+]);
 /** Empty routing values are not meaningful credentials/endpoints. Ignore them at each precedence layer so
  *  an empty project override (or launcher-exported empty env var) cannot hide a valid global config value. */
 function withoutBlankRoutingValues(input) {
@@ -78,7 +87,7 @@ function readProjectConfig(cwd) {
         const p = join(dir, ".hara", "config.json");
         if (existsSync(p)) {
             try {
-                return JSON.parse(readFileSync(p, "utf8"));
+                return configRecord(JSON.parse(readFileSync(p, "utf8")));
             }
             catch {
                 return {};
@@ -139,14 +148,15 @@ export function loadConfig(opts = {}) {
     // Strip both the new (`overlays`) and legacy (`profiles`) overlay containers from the base merge.
     // The legacy `profiles` key is kept readable for back-compat with users who already have it.
     const { overlays, profiles, ...globalBase } = global;
-    const project = readProjectConfig(process.cwd());
-    const overlayName = process.env.HARA_OVERLAY ?? opts.overlay;
+    const effectiveCwd = resolve(opts.cwd ?? process.cwd());
+    const project = readProjectConfig(effectiveCwd);
+    const overlayName = nonBlankEnv(process.env.HARA_OVERLAY) ?? nonBlankEnv(opts.overlay);
     const overlayMap = overlays && typeof overlays === "object" ? overlays : profiles && typeof profiles === "object" ? profiles : null;
-    const overlay = overlayName && overlayMap && overlayMap[overlayName] ? overlayMap[overlayName] : {};
+    const overlay = configRecord(overlayName && overlayMap ? overlayMap[overlayName] : undefined);
     const merged = {
         ...withoutBlankRoutingValues(globalBase),
-        ...withoutBlankRoutingValues(project),
         ...withoutBlankRoutingValues(overlay),
+        ...withoutBlankRoutingValues(project),
     };
     const provider = (nonBlankEnv(process.env.HARA_PROVIDER) ?? merged.provider ?? "anthropic");
     const d = PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic;
@@ -160,21 +170,21 @@ export function loadConfig(opts = {}) {
     const assetCapture = (process.env.HARA_ASSET_CAPTURE ?? merged.assetCapture ?? "ask");
     const computerUse = (process.env.HARA_COMPUTER_USE ?? merged.computerUse ?? "off");
     const computerApps = String(process.env.HARA_COMPUTER_APPS ?? merged.computerApps ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-    const visionModel = process.env.HARA_VISION_MODEL ?? merged.visionModel;
-    const visionBaseURL = process.env.HARA_VISION_BASE_URL ?? merged.visionBaseURL;
-    const visionApiKey = process.env.HARA_VISION_API_KEY ?? merged.visionApiKey;
+    const visionModel = nonBlankEnv(process.env.HARA_VISION_MODEL) ?? merged.visionModel;
+    const visionBaseURL = nonBlankEnv(process.env.HARA_VISION_BASE_URL) ?? merged.visionBaseURL;
+    const visionApiKey = nonBlankEnv(process.env.HARA_VISION_API_KEY) ?? merged.visionApiKey;
     const modelVision = merged.modelVision && typeof merged.modelVision === "object" ? merged.modelVision : {};
-    const embedProvider = (process.env.HARA_EMBED_PROVIDER ?? merged.embedProvider ?? "off");
-    const embedModel = process.env.HARA_EMBED_MODEL ?? merged.embedModel;
-    const embedBaseURL = process.env.HARA_EMBED_BASE_URL ?? merged.embedBaseURL;
-    const embedApiKey = process.env.HARA_EMBED_API_KEY ?? merged.embedApiKey;
-    const routeModel = process.env.HARA_ROUTE_MODEL ?? merged.routeModel;
-    const routeBaseURL = process.env.HARA_ROUTE_BASE_URL ?? merged.routeBaseURL;
-    const routeApiKey = process.env.HARA_ROUTE_API_KEY ?? merged.routeApiKey;
+    const embedProvider = (nonBlankEnv(process.env.HARA_EMBED_PROVIDER) ?? merged.embedProvider ?? "off");
+    const embedModel = nonBlankEnv(process.env.HARA_EMBED_MODEL) ?? merged.embedModel;
+    const embedBaseURL = nonBlankEnv(process.env.HARA_EMBED_BASE_URL) ?? merged.embedBaseURL;
+    const embedApiKey = nonBlankEnv(process.env.HARA_EMBED_API_KEY) ?? merged.embedApiKey;
+    const routeModel = nonBlankEnv(process.env.HARA_ROUTE_MODEL) ?? merged.routeModel;
+    const routeBaseURL = nonBlankEnv(process.env.HARA_ROUTE_BASE_URL) ?? merged.routeBaseURL;
+    const routeApiKey = nonBlankEnv(process.env.HARA_ROUTE_API_KEY) ?? merged.routeApiKey;
     const mcpServers = {
         ...(globalBase.mcpServers ?? {}),
-        ...(project.mcpServers ?? {}),
         ...(overlay.mcpServers ?? {}),
+        ...(project.mcpServers ?? {}),
     };
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
     // Guardian: default ON; env HARA_GUARDIAN=0/off/false or config guardian:"off" disables it.
@@ -185,15 +195,15 @@ export function loadConfig(opts = {}) {
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
     const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
-    const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
-    const fallbackProvider = (process.env.HARA_FALLBACK_PROVIDER ?? merged.fallbackProvider);
-    const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
-    const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
+    const fallbackModel = nonBlankEnv(process.env.HARA_FALLBACK_MODEL) ?? merged.fallbackModel;
+    const fallbackProvider = (nonBlankEnv(process.env.HARA_FALLBACK_PROVIDER) ?? merged.fallbackProvider);
+    const fallbackBaseURL = nonBlankEnv(process.env.HARA_FALLBACK_BASE_URL) ?? merged.fallbackBaseURL;
+    const fallbackApiKey = nonBlankEnv(process.env.HARA_FALLBACK_API_KEY) ?? merged.fallbackApiKey;
     const reasoningRaw = process.env.HARA_REASONING_EFFORT ?? merged.reasoningEffort;
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high", "max"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/cron/deliver.js

@@ -1,15 +1,39 @@
+// Cron result delivery — push a finished job's output to a chat channel (openclaw/hermes parity),
+// WITHOUT needing the gateway process: adapters are constructed one-shot from the same env vars the
+// gateway uses, send once, and are dropped. Spec format: "<target>:<id>" —
+//   telegram:<chatId>   (HARA_TELEGRAM_TOKEN)
+//   feishu:<chatId>     (HARA_FEISHU_APP_ID + HARA_FEISHU_APP_SECRET)
+//   webhook:<url>       (plain POST {name,status,text} JSON — for anything else)
+//   weixin:<peerId>     (sends over stored ~/.hara/weixin creds — explicit peer required; guessing the
+//                        "owner" from a multi-DM context-token cache can deliver private results to the wrong person)
+// Adapters are imported LAZILY so the (heavy) SDKs never load unless a job actually delivers.
 /** Parse a `--deliver` spec; error string on anything unsupported (listing what IS supported). */
 export function parseDeliver(spec) {
     const i = spec.indexOf(":");
     if (i <= 0)
-        return { error: `bad deliver spec "${spec}" — use telegram:<chatId>, feishu:<chatId>, or webhook:<url>` };
+        return { error: `bad deliver spec "${spec}" — use telegram:<chatId>, feishu:<chatId>, weixin:<peerId>, or webhook:<url>` };
     const platform = spec.slice(0, i).toLowerCase();
     const to = spec.slice(i + 1).trim();
     if (!to)
         return { error: `deliver spec "${spec}" is missing a target after ":"` };
-    if (platform === "telegram" || platform === "feishu" || platform === "webhook")
+    if (platform === "weixin" && to.toLowerCase() === "owner") {
+        return { error: "weixin:owner is ambiguous when several people have messaged the bot — use an explicit weixin:<peerId>" };
+    }
+    if (platform === "telegram" || platform === "feishu" || platform === "webhook" || platform === "weixin")
         return { platform, to };
-    return { error: `unsupported deliver platform "${platform}" — supported: telegram, feishu, webhook (WeChat needs the live gateway)` };
+    return { error: `unsupported deliver platform "${platform}" — supported: telegram, feishu, weixin, webhook` };
+}
+/** Flatten markdown for plain-text chat surfaces (Feishu/WeChat/Telegram text messages render syntax
+ *  literally): drop code fences/inline backticks/bold/headers, turn [text](url) into "text (url)". */
+export function plainChat(text) {
+    return text
+        .replace(/```[a-zA-Z0-9_-]*\n?/g, "")
+        .replace(/```/g, "")
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/__([^_]+)__/g, "$1")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
 }
 /** Send `text` to the target. Returns null on success, or an error string (never throws — cron
  *  delivery is best-effort and must not kill the tick). */
@@ -17,6 +41,8 @@ export async function deliverResult(spec, text) {
     const t = parseDeliver(spec);
     if ("error" in t)
         return t.error;
+    if (t.platform !== "webhook")
+        text = plainChat(text); // chat surfaces are plain text; webhooks get raw payload
     try {
         if (t.platform === "webhook") {
             const r = await fetch(t.to, {
@@ -35,6 +61,14 @@ export async function deliverResult(spec, text) {
             await telegramAdapter(token).send(t.to, text);
             return null;
         }
+        if (t.platform === "weixin") {
+            const { loadWeixinCreds, weixinAdapter } = await import("../gateway/weixin.js");
+            const creds = loadWeixinCreds();
+            if (!creds)
+                return "hara weixin not logged in (~/.hara/weixin/creds.json missing)";
+            await weixinAdapter(creds).send(t.to, text);
+            return null;
+        }
         // feishu
         const appId = process.env.HARA_FEISHU_APP_ID;
         const appSecret = process.env.HARA_FEISHU_APP_SECRET;

package/dist/feedback.js

@@ -41,9 +41,10 @@ export function buildIssueBody(description, env, sessionTail) {
     parts.push("---", "_filed via `hara feedback`_");
     return parts.join("\n");
 }
-/** Issue title from the description: first line, trimmed, capped. */
+/** Issue title from the description: first line, redacted BEFORE it crosses the public issue boundary,
+ *  trimmed and capped. Body-only redaction is insufficient because GitHub titles are public too. */
 export function issueTitle(description) {
-    const first = (description.trim().split("\n")[0] || "feedback").trim();
+    const first = redact((description.trim().split("\n")[0] || "feedback").trim());
     return first.length > 70 ? first.slice(0, 67) + "…" : first;
 }
 export const FEEDBACK_REPO = "hara-cli/hara";

package/dist/fs-read.js

@@ -1,20 +1,92 @@
 // Bounded streaming line reader for files too large to load as one string. It stores only the requested
 // window and a capped prefix of each line, so huge logs/JSONL and minified one-line files stay safe.
-import { closeSync, createReadStream, fstatSync, openSync, readSync } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { open } from "node:fs/promises";
 export class BinaryFileError extends Error {
     constructor(path) {
         super(`${path} appears to be binary (NUL byte detected)`);
         this.name = "BinaryFileError";
     }
 }
+export class NonRegularFileError extends Error {
+    code = "HARA_NOT_REGULAR_FILE";
+    constructor(path) {
+        super(`${path} is not a regular file`);
+        this.name = "NonRegularFileError";
+    }
+}
+export class FileReadLimitError extends Error {
+    limit;
+    code = "HARA_FILE_TOO_LARGE";
+    constructor(path, limit) {
+        super(`${path} exceeds the ${limit}-byte safe edit/read limit`);
+        this.limit = limit;
+        this.name = "FileReadLimitError";
+    }
+}
 const DEFAULT_LINE_CAP = 2000;
 const DEFAULT_MAX_SCAN = 64 * 1024 * 1024;
+const MAX_SLICE_LINES = 2_000;
+/** Editing tools materialize the old text for diff/CAS. Keep that allocation explicitly bounded. */
+export const MAX_EDIT_READ_BYTES = 64 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+const MAX_PREFIX_CHARS = 1_000_000;
+/** Open without blocking on a FIFO, validate the SAME descriptor, then read at most maxBytes from it.
+ * Path-level stat→readFile is unsafe because the path can be exchanged for a pipe/device between calls. */
+async function readRegularFileSnapshotWithFlags(path, maxBytes, flags) {
+    const requested = Number.isFinite(maxBytes) ? Math.floor(maxBytes) : MAX_EDIT_READ_BYTES;
+    const limit = Math.min(MAX_EDIT_READ_BYTES, Math.max(1, requested));
+    const handle = await open(path, flags);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new NonRegularFileError(path);
+        if (info.size > limit)
+            throw new FileReadLimitError(path, limit);
+        const chunks = [];
+        let total = 0;
+        let position = 0;
+        // Read one byte past the limit so concurrent growth cannot bypass the pre-read size check.
+        while (total <= limit) {
+            const want = Math.min(READ_CHUNK_BYTES, limit + 1 - total);
+            const buffer = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buffer, 0, want, position);
+            if (bytesRead === 0)
+                break;
+            chunks.push(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+            position += bytesRead;
+        }
+        if (total > limit)
+            throw new FileReadLimitError(path, limit);
+        return { text: Buffer.concat(chunks, total).toString("utf8"), dev: info.dev, ino: info.ino, mode: info.mode & 0o777, nlink: info.nlink };
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+export async function readRegularFileSnapshot(path, maxBytes = MAX_EDIT_READ_BYTES) {
+    return readRegularFileSnapshotWithFlags(path, maxBytes, constants.O_RDONLY | constants.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);
+}
+export async function readRegularFileText(path, maxBytes = MAX_EDIT_READ_BYTES) {
+    return (await readRegularFileSnapshot(path, maxBytes)).text;
+}
 /** Read only enough bytes to produce a bounded UTF-8 prefix (used by synchronous @file expansion). */
 export function readTextPrefixSync(path, maxChars) {
-    const chars = Math.max(0, Math.floor(maxChars));
-    const fd = openSync(path, "r");
+    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);
     try {
-        const size = fstatSync(fd).size;
+        const info = fstatSync(fd);
+        if (!info.isFile())
+            throw new NonRegularFileError(path);
+        const size = info.size;
         // Four bytes per Unicode scalar plus a small boundary cushion guarantees enough decoded input for
         // `chars` without allocating the entire file. readSync can short-read, so fill in a loop.
         const byteLimit = Math.min(size, chars * 4 + 4);
@@ -41,11 +113,19 @@ export function readTextPrefixSync(path, maxChars) {
 }
 /** Render a line slice without retaining the entire file. Total line count is shown only when EOF is reached. */
 export async function streamFileSlice(path, offset = 1, limit = 300, options = {}) {
-    const start = Math.max(1, Math.floor(offset));
-    const want = Math.max(1, Math.floor(limit));
+    const requestedStart = Number.isFinite(offset) ? Math.floor(offset) : 1;
+    const requestedLines = Number.isFinite(limit) ? Math.floor(limit) : 300;
+    const start = Math.min(Number.MAX_SAFE_INTEGER, Math.max(1, requestedStart));
+    const want = Math.min(MAX_SLICE_LINES, Math.max(1, requestedLines));
     const requestedEnd = start + want - 1;
-    const lineCap = Math.max(1, Math.floor(options.lineCap ?? DEFAULT_LINE_CAP));
-    const maxScan = Math.max(lineCap, Math.floor(options.maxScanChars ?? DEFAULT_MAX_SCAN));
+    const requestedLineCap = Number.isFinite(options.lineCap)
+        ? Math.floor(options.lineCap)
+        : DEFAULT_LINE_CAP;
+    const lineCap = Math.min(DEFAULT_LINE_CAP, Math.max(1, requestedLineCap));
+    const requestedScan = Number.isFinite(options.maxScanChars)
+        ? Math.floor(options.maxScanChars)
+        : DEFAULT_MAX_SCAN;
+    const maxScan = Math.min(DEFAULT_MAX_SCAN, Math.max(lineCap, requestedScan));
     const rendered = [];
     let lineNo = 1;
     let linePrefix = "";
@@ -98,8 +178,17 @@ export async function streamFileSlice(path, offset = 1, limit = 300, options = {
         if (current > requestedEnd)
             hasMore = true;
     };
-    const stream = createReadStream(path, { encoding: "utf8", highWaterMark: 64 * 1024 });
+    // Keep validation and streaming on the same non-blocking descriptor. This closes the stat→open race
+    // where an attacker/local generator exchanges a regular path for a FIFO after validation.
+    const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    let stream;
     try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new NonRegularFileError(path);
+        // `end` is an inclusive byte offset. It makes the scan ceiling a true fd-level byte bound (not just
+        // a post-read character counter, which could overshoot badly on multi-byte text or a giant chunk).
+        stream = handle.createReadStream({ encoding: "utf8", highWaterMark: 64 * 1024, autoClose: false, end: maxScan - 1 });
         for await (const raw of stream) {
             const chunk = String(raw);
             if (chunk.length)
@@ -125,17 +214,22 @@ export async function streamFileSlice(path, offset = 1, limit = 300, options = {
                 stoppedEarly = true;
                 break;
             }
-            if (scanned >= maxScan) {
+        }
+        if (!stoppedEarly && stream.bytesRead >= maxScan) {
+            // Re-fstat the same open file description so concurrent growth is also detected. An exact-size file
+            // is genuine EOF and should still receive the normal total-line rendering.
+            const latest = await handle.stat();
+            if (latest.size > stream.bytesRead) {
                 scanLimited = true;
                 stoppedEarly = true;
                 if (lineNo >= start && lineNo <= requestedEnd)
                     finishLine(true);
-                break;
             }
         }
     }
     finally {
-        stream.destroy();
+        stream?.destroy();
+        await handle.close().catch(() => { });
     }
     if (!stoppedEarly) {
         // A trailing newline creates no phantom line, matching String#split + trailing-empty removal.