@fusengine/harness 0.1.90 → 0.1.91

package/src/codex-rules/rules/ask.ts

@@ -0,0 +1,44 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `prompt`-decision rules — hand-mapped 1:1 from `security.ts`'s
+ * ASK_PATTERNS. `DANGEROUS PATTERN: chmod 777` lives in `chmod-ask.ts`
+ * (needed multiple flag-order variants). `DANGEROUS PATTERN: write to /etc`
+ * is intentionally absent here: it fires on shell redirection
+ * (`> /etc/...`), which is not a single argv invocation — see
+ * `../skip-list.ts`.
+ */
+export const ASK_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive chown",
+    pattern: ["chown", "-R"],
+    decision: "prompt",
+    justification: "Recursive ownership change; confirm scope.",
+    match: ["chown -R user:user /srv/app"],
+    notMatch: ["chown user file.txt"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: eval",
+    pattern: ["eval"],
+    decision: "prompt",
+    justification: "Evaluates arbitrary shell input.",
+    match: ["eval $(cat script.sh)"],
+    notMatch: ["node eval.js"],
+  },
+  {
+    sourceLabel: "DELETE: 'rm' permanently deletes - confirmation required",
+    pattern: ["rm"],
+    decision: "prompt",
+    justification: "rm permanently deletes; confirm before running.",
+    match: ["rm file.txt"],
+    notMatch: ["rmdir empty"],
+  },
+  {
+    sourceLabel: "DELETE: 'unlink' command detected - confirmation required",
+    pattern: ["unlink"],
+    decision: "prompt",
+    justification: "unlink permanently removes a file; confirm before running.",
+    match: ["unlink file.txt"],
+    notMatch: ["ln -s a b"],
+  },
+];

package/src/codex-rules/rules/chmod-ask.ts

@@ -0,0 +1,57 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `chmod 777` `prompt`-decision variants — hand-mapped from `security.ts`'s
+ * `DANGEROUS PATTERN: chmod 777` ASK_PATTERNS label. The source regex
+ * accepts any chain of `-[a-zA-Z]+` flags before `777`; `prefix_rule` needs
+ * one literal-token variant per common flag order, so every frequent
+ * ordering is enumerated. Always `prompt`: `prefix_rule` cannot distinguish
+ * an absolute-path target from a relative one, so both are prompted rather
+ * than letting an absolute-path `chmod 777` fall through silently.
+ */
+export const CHMOD_ASK_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions; confirm the target is intended.",
+    match: ["chmod 777 file.txt", "chmod 777 /tmp/file"],
+    notMatch: ["chmod 755 file.txt"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "-R", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions, recursive; confirm the target is intended.",
+    match: ["chmod -R 777 dir"],
+    notMatch: ["chmod -R 755 dir"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "-r", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions, recursive (lowercase flag); confirm the target is intended.",
+    match: ["chmod -r 777 dir"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "-v", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions, verbose flag; confirm the target is intended.",
+    match: ["chmod -v 777 file.txt"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "-Rv", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions, combined recursive+verbose flags; confirm the target is intended.",
+    match: ["chmod -Rv 777 dir"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777",
+    pattern: ["chmod", "-vR", "777"],
+    decision: "prompt",
+    justification: "World-writable permissions, combined verbose+recursive flags; confirm the target is intended.",
+    match: ["chmod -vR 777 dir"],
+  },
+];

package/src/codex-rules/rules/dd.ts

@@ -0,0 +1,23 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `dd` — hand-mapped from `security.ts`'s `CRITICAL: Detected dangerous
+ * command 'dd if='` label (source regex only fires on `of=/dev/...`).
+ * Owner decision: DOWNGRADE forbidden -> prompt. `prefix_rule` cannot
+ * glob-match a `key=value` argv token against a raw-device path, so a
+ * literal forbidden translation would silently block legitimate
+ * `dd if=a.img of=b.img` usage — prompting on every `dd` invocation instead
+ * never lets a raw-disk write through silently, without blocking safe use.
+ */
+export const DD_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'dd if='",
+    pattern: ["dd"],
+    decision: "prompt",
+    justification:
+      "dd can overwrite a raw block device via of=/dev/...; prompts on every dd invocation " +
+      "(broader than security.ts, which only fires on of=/dev/*) because execpolicy cannot " +
+      "glob-match that argv token — owner decision: do not block legitimate dd usage.",
+    match: ["dd if=/dev/zero of=/dev/sda", "dd if=a.img of=b.img"],
+  },
+];

package/src/codex-rules/rules/diskutil.ts

@@ -0,0 +1,33 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `diskutil` erase/partition variants — hand-mapped from `security.ts`'s
+ * case-insensitive `\bdiskutil\s+(?:erase|partitionDisk)\b/i` CRITICAL
+ * label. `prefix_rule` has no case-insensitive matching, so every real
+ * casing macOS users actually type (camelCase, all-lowercase, all-caps) is
+ * enumerated explicitly as an alternation at position 1.
+ */
+export const DISKUTIL_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'diskutil erase'",
+    pattern: [
+      "diskutil",
+      [
+        "erase",
+        "eraseDisk",
+        "erasedisk",
+        "ERASEDISK",
+        "eraseVolume",
+        "erasevolume",
+        "ERASEVOLUME",
+        "partitionDisk",
+        "partitiondisk",
+        "PARTITIONDISK",
+      ],
+    ],
+    decision: "forbidden",
+    justification: "Erases or repartitions a macOS disk/volume (case-variant enumeration; execpolicy has no case-insensitive match).",
+    match: ["diskutil eraseDisk /dev/disk2", "diskutil ERASEDISK /dev/disk2", "diskutil erase /dev/disk2"],
+    notMatch: ["diskutil list"],
+  },
+];

package/src/codex-rules/rules/mkfs.ts

@@ -0,0 +1,42 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `mkfs` filesystem-formatting variants — hand-mapped from `security.ts`'s
+ * `\bmkfs(?:\.[a-z0-9]+)?\b` CRITICAL_PATTERNS label. The source regex
+ * accepts ANY `.suffix`; `prefix_rule` cannot express an open-ended suffix,
+ * so every real-world `mkfs.*` filesystem type is enumerated explicitly as
+ * an alternation at position 0 (exhaustive, not a mechanical derivation).
+ */
+export const MKFS_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'mkfs'",
+    pattern: [
+      [
+        "mkfs",
+        "mkfs.ext2",
+        "mkfs.ext3",
+        "mkfs.ext4",
+        "mkfs.xfs",
+        "mkfs.btrfs",
+        "mkfs.exfat",
+        "mkfs.vfat",
+        "mkfs.fat",
+        "mkfs.ntfs",
+        "mkfs.f2fs",
+        "mkfs.hfsplus",
+        "mkfs.apfs",
+        "mkfs.msdos",
+        "mkfs.minix",
+        "mkfs.jfs",
+        "mkfs.reiserfs",
+        "mkfs.udf",
+        "mkfs.bfs",
+        "mkfs.cramfs",
+      ],
+    ],
+    decision: "forbidden",
+    justification: "Formats a block device, destroying its contents (exhaustive mkfs.* variant enumeration).",
+    match: ["mkfs.exfat /dev/sda1", "mkfs.f2fs /dev/sdb1", "mkfs /dev/sdb1", "mkfs.ext4 /dev/sda1"],
+    notMatch: ["ls /dev"],
+  },
+];

package/src/codex-rules/rules/privilege.ts

@@ -0,0 +1,49 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * Privilege-escalation binaries — hand-mapped 1:1 from `security.ts`'s
+ * `sudo`/`su`/`doas`/`passwd`/`del` CRITICAL_PATTERNS labels (parity
+ * `security_rules.PRIVILEGE_COMMANDS`).
+ */
+export const PRIVILEGE_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "PRIVILEGE ESCALATION: sudo",
+    pattern: ["sudo"],
+    decision: "forbidden",
+    justification: "Runs a command with elevated privileges.",
+    match: ["sudo rm -rf /tmp"],
+    notMatch: ["echo sudo"],
+  },
+  {
+    sourceLabel: "PRIVILEGE ESCALATION: su",
+    pattern: ["su"],
+    decision: "forbidden",
+    justification: "Switches to another user, typically root.",
+    match: ["su -", "su root"],
+    notMatch: ["sudo ls"],
+  },
+  {
+    sourceLabel: "PRIVILEGE ESCALATION: doas",
+    pattern: ["doas"],
+    decision: "forbidden",
+    justification: "BSD-style sudo alternative for elevated privileges.",
+    match: ["doas reboot"],
+    notMatch: ["ls"],
+  },
+  {
+    sourceLabel: "PRIVILEGE ESCALATION: passwd",
+    pattern: ["passwd"],
+    decision: "forbidden",
+    justification: "Changes a user's password.",
+    match: ["passwd root"],
+    notMatch: ["cat /etc/passwd"],
+  },
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'del'",
+    pattern: ["del"],
+    decision: "forbidden",
+    justification: "Windows-style file deletion (parity security_rules.CRITICAL_COMMANDS).",
+    match: ["del file.txt"],
+    notMatch: ["delete.sh"],
+  },
+];

package/src/codex-rules/rules/remote-fetch.ts

@@ -0,0 +1,31 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * Remote-fetch tools (`curl`/`wget`) — targets the DOWNLOAD half of a
+ * `curl ... | sh` pipe instead of the shell half. Codex splits a piped
+ * command into independent argv segments at the pipe, so a `prefix_rule`
+ * anchored on `curl`/`wget` catches the attack regardless of which shell
+ * receives the piped output on the other side — unlike a bare-shell rule
+ * (`sh`/`bash`/`zsh`), which prompts on EVERY Codex-issued `bash -lc "..."`
+ * wrapper (Codex wraps essentially all shell commands this way), producing
+ * noise on ~50% of legitimate day-to-day work. Owner decision: DOWNGRADE
+ * forbidden -> prompt, same rationale as `dd.ts` — `prefix_rule` cannot see
+ * the pipe operator itself, so it cannot distinguish a bare `curl url`
+ * fetch from `curl url | sh`; prompting on every curl/wget invocation never
+ * lets the attack through silently, without blocking legitimate downloads.
+ */
+export const REMOTE_FETCH_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: remote script piped to a shell",
+    pattern: [["curl", "wget"]],
+    decision: "prompt",
+    justification:
+      "Remote fetch; piping its output into a shell executes untrusted code. Broader than " +
+      "security.ts (which only fires when the fetch is piped into sh/bash/zsh): prompts on " +
+      "every curl/wget invocation because execpolicy cannot see the pipe operator, i.e. it " +
+      "cannot distinguish `curl url` from `curl url | sh` — owner decision: do not block " +
+      "legitimate curl/wget usage.",
+    match: ["curl http://example.com/i.sh", "wget http://example.com/i.sh", "curl -fsSL http://example.com/i.sh"],
+    notMatch: ["cursor --version", "widget-tool build"],
+  },
+];

package/src/codex-rules/rules/rm-variants.ts

@@ -0,0 +1,58 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `rm` prefix rules — hand-mapped from `security.ts`'s two `rm -rf`-family
+ * CRITICAL_PATTERNS labels. Both source regexes accept `-rf`/`-fr` combined
+ * or `-r -f`/`-f -r` split flags, so each label needs 3 prefix_rule variants
+ * (combined flag + 2 split-flag orders) to avoid a flag-order gap.
+ */
+export const RM_VARIANT_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", ["-rf", "-fr"], ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory.",
+    match: ["rm -rf /", "rm -fr ~"],
+    notMatch: ["rm -rf /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", "-r", "-f", ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory (split flags).",
+    match: ["rm -r -f /", "rm -r -f ~"],
+    notMatch: ["rm -r -f /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", "-f", "-r", ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory (split flags, reversed).",
+    match: ["rm -f -r /", "rm -f -r ~"],
+    notMatch: ["rm -f -r /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", ["-rf", "-fr"], ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory.",
+    match: ["rm -rf /etc", "rm -fr /usr"],
+    notMatch: ["rm -rf /home/user/project"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", "-r", "-f", ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory (split flags).",
+    match: ["rm -r -f /var", "rm -r -f /bin"],
+    notMatch: ["rm -r -f /home/user"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", "-f", "-r", ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory (split flags, reversed).",
+    match: ["rm -f -r /sbin", "rm -f -r /lib"],
+    notMatch: ["rm -f -r /tmp"],
+  },
+];

package/src/codex-rules/rules/single-commands.ts

@@ -0,0 +1,57 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * Single-purpose destructive binaries — hand-mapped 1:1 from `security.ts`'s
+ * `chmod 777 on /`, `shred`, `fdisk` CRITICAL_PATTERNS labels. `mkfs`,
+ * `dd`, and `diskutil erase` live in their own files (`mkfs.ts`, `dd.ts`,
+ * `diskutil.ts`) — each needed a wider case/variant enumeration than fits
+ * this file's SRP scope. The root-chmod rule needs the same flag-order
+ * alternation as `chmod-ask.ts` — source security.ts accepts flags before
+ * `777` for the root case too (`chmod -R 777 /` is still CRITICAL there).
+ */
+export const SINGLE_COMMAND_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root.",
+    match: ["chmod 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-R", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, recursive.",
+    match: ["chmod -R 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-r", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, recursive (lowercase flag).",
+    match: ["chmod -r 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-v", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, verbose flag.",
+    match: ["chmod -v 777 /"],
+  },
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'shred'",
+    pattern: ["shred"],
+    decision: "forbidden",
+    justification: "Irreversibly overwrites file contents.",
+    match: ["shred -u secrets.txt"],
+    notMatch: ["cat secrets.txt"],
+  },
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'fdisk'",
+    pattern: ["fdisk"],
+    decision: "forbidden",
+    justification: "Edits disk partition tables.",
+    match: ["fdisk /dev/sda"],
+    notMatch: ["cat /proc/partitions"],
+  },
+];

package/src/codex-rules/skip-list.ts

@@ -0,0 +1,25 @@
+import type { CodexSkipEntry } from "./types";
+
+/**
+ * `security.ts` labels with NO argv-prefix equivalent. Every entry here is
+ * shell syntax (pipes, redirection, function-definition syntax) that never
+ * appears as a plain argv token when a command is exec'd without a shell —
+ * Codex execpolicy's `prefix_rule` cannot express them. Covered instead by
+ * `sandbox_mode`/`approval_policy`. Never drop a label silently: it is
+ * either a prefix_rule (see `rules/`) or an entry here.
+ */
+export const SKIP_LIST: CodexSkipEntry[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: fork bomb",
+    reason:
+      "Shell function-definition syntax `:(){ :|:& };:` is not a single argv invocation — no prefix_rule can express it.",
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: redirect to a raw disk device",
+    reason: "`>`/`>>` redirection to /dev/sda is shell syntax, invisible to argv-prefix matching.",
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: write to /etc",
+    reason: "`>`/`>>` redirection into /etc/* is shell syntax, invisible to argv-prefix matching.",
+  },
+];

package/src/codex-rules/starlark.ts

@@ -0,0 +1,46 @@
+import type { CodexPrefixRule } from "./types";
+
+/**
+ * Neutralize characters that would break out of a Starlark `#` line comment
+ * (a bare `\n`/`\r` in an interpolated label/reason would start a new line
+ * no longer prefixed by `#`, corrupting the generated file).
+ */
+export function sanitizeComment(text: string): string {
+  return text.replace(/[\r\n]+/g, " ");
+}
+
+/** Render a string array as a Starlark list literal (double-quoted strings). */
+function starlarkList(values: string[]): string {
+  return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+
+/** Render one pattern element: a bare token, or a `[...]` alternation. */
+function starlarkPatternElement(el: string | string[]): string {
+  return Array.isArray(el) ? starlarkList(el) : JSON.stringify(el);
+}
+
+/**
+ * Render a single `CodexPrefixRule` as a Starlark `prefix_rule(...)` call,
+ * prefixed by a traceability comment pointing back at its `security.ts` label.
+ */
+export function renderPrefixRule(rule: CodexPrefixRule): string {
+  const pattern = `[${rule.pattern.map(starlarkPatternElement).join(", ")}]`;
+  const lines = [
+    `# source: security.ts label "${sanitizeComment(rule.sourceLabel)}"`,
+    "prefix_rule(",
+    `    pattern = ${pattern},`,
+    `    decision = "${rule.decision}",`,
+    `    justification = ${JSON.stringify(rule.justification)},`,
+    `    match = ${starlarkList(rule.match)},`,
+  ];
+  if (rule.notMatch && rule.notMatch.length > 0) {
+    lines.push(`    not_match = ${starlarkList(rule.notMatch)},`);
+  }
+  lines.push(")");
+  return lines.join("\n");
+}
+
+/** Render a list of rules, each block separated by a blank line. */
+export function renderPrefixRules(rules: CodexPrefixRule[]): string {
+  return rules.map(renderPrefixRule).join("\n\n");
+}

package/src/codex-rules/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for the Codex execpolicy `.rules` (Starlark) generator.
+ * Verified contract (openai/codex `codex-rs/execpolicy/README.md` +
+ * learn.chatgpt.com/docs/agent-configuration/rules): `prefix_rule(pattern,
+ * decision, justification?, match?, not_match?)`; decisions are
+ * allow < prompt < forbidden (strictest wins across matching rules);
+ * `match`/`not_match` are validated as inline unit tests at file-load time.
+ */
+
+/** Codex execpolicy decision severity. */
+export type CodexDecision = "allow" | "prompt" | "forbidden";
+
+/**
+ * One argv-prefix rule, hand-mapped from a single `security.ts`
+ * `LabeledPattern`. `pattern` entries are exact argv tokens; a nested
+ * array element means "any of these tokens at this position" (Codex
+ * execpolicy alternation) — never a mechanical regex-to-prefix derivation.
+ */
+export interface CodexPrefixRule {
+  /** Exact `label` string from `CRITICAL_PATTERNS`/`ASK_PATTERNS` this rule maps to. */
+  sourceLabel: string;
+  /** Argv-prefix tokens; an element may be `string[]` for alternation. */
+  pattern: (string | string[])[];
+  decision: CodexDecision;
+  justification: string;
+  /** Example invocations that must satisfy this rule (validated at load time). */
+  match: string[];
+  /** Example invocations that must NOT satisfy this rule (validated at load time). */
+  notMatch?: string[];
+}
+
+/** A `security.ts` label with no argv-prefix equivalent — named, never dropped silently. */
+export interface CodexSkipEntry {
+  sourceLabel: string;
+  reason: string;
+}

package/src/config/dotenv.ts

@@ -0,0 +1,55 @@
+/**
+ * Native .env loader. Ports the claude-plugins `services/env-file.ts`
+ * (`loadEnvFile`) into the engine so a hook run hydrates `process.env` from the
+ * harness home `.env` (`~/.claude/.env`, `~/.codex/.env`, …) plus the project
+ * `<cwd>/.env`, instead of relying on Bun auto-dotenv or `BASH_ENV`. A value
+ * already present in the environment always wins (the file never overwrites it).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { harnessHome } from "./home-dir";
+import type { HarnessId } from "../detect/harness";
+
+/** Home config dir holding the `.env` for each harness (defaults to `.claude`). */
+export const HOME_DIR: Partial<Record<HarnessId, string>> = {
+  "claude-code": ".claude", codex: ".codex", cursor: ".cursor",
+  cline: ".clinerules", "gemini-cli": ".gemini", opencode: ".opencode",
+  hermes: ".hermes", kimi: ".kimi-code",
+};
+
+/** Parse a `.env` file into a key→value map (`export KEY="v"` or `KEY=v`). */
+export function parseEnvFile(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  let content = "";
+  try { content = readFileSync(path, "utf-8"); } catch { return {}; }
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    if (line.trimStart().startsWith("#")) continue;
+    const m = line.match(/^\s*(?:export\s+)?(\w+)\s*=\s*["']?([^"'\n]*)["']?\s*$/);
+    if (m?.[1]) out[m[1]] = m[2] ?? "";
+  }
+  return out;
+}
+
+/** The `.env` paths probed for a harness: home `.env` then `<cwd>/.env`. */
+export function envCandidates(id: HarnessId, home: string = homedir(), cwd: string = process.cwd()): string[] {
+  return [join(harnessHome(id, process.env, home), ".env"), join(cwd, ".env")];
+}
+
+/**
+ * Load `.env` files into `env` without overwriting existing keys. Reads the
+ * harness home `.env` then `<cwd>/.env`. Best-effort (missing/unreadable files
+ * are skipped) so a hook never fails on env loading.
+ * @param id - Detected harness id (selects the home dir).
+ * @param env - Target environment (defaults to `process.env`).
+ * @param home - Home dir.
+ * @param cwd - Project root.
+ */
+export function loadDotenv(id: HarnessId, env: NodeJS.ProcessEnv = process.env, home: string = homedir(), cwd: string = process.cwd()): void {
+  for (const path of envCandidates(id, home, cwd)) {
+    for (const [k, v] of Object.entries(parseEnvFile(path))) {
+      if (env[k] === undefined) env[k] = v;
+    }
+  }
+}

package/src/config/env.ts

@@ -0,0 +1,10 @@
+/**
+ * Robust integer-from-env parser.
+ * undefined / empty / whitespace / NaN / float / <= 0 all fall back to `fallback`.
+ * `Number("")` is 0, so the empty guard is required before `Number()`.
+ */
+export function parseEnvInt(raw: string | undefined, fallback: number): number {
+  if (!raw?.trim()) return fallback;
+  const n = Number(raw.trim());
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}

package/src/config/home-dir.ts

@@ -0,0 +1,36 @@
+/**
+ * Harness home-dir resolution with env overrides. `dotenv.ts`'s static
+ * `HOME_DIR` table knows every harness's default config dir but cannot move
+ * with the user's data root — Kimi Code CLI documents `KIMI_CODE_HOME` for
+ * exactly that (isolated data roots get isolated skills/agents/hooks), so the
+ * override is honored here instead of hardcoding `~/.kimi-code`.
+ *
+ * Deliberately consumed only where a USER-HOME path is built (`envCandidates`
+ * today): `harnessHomeSegment` (`policy/apex-target.ts`) also serves
+ * project-relative joins (`<project>/.kimi-code/apex`), which an absolute
+ * override would corrupt — those sites stay segment-based.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessId } from "../detect/harness";
+import { HOME_DIR } from "./dotenv";
+
+/** Documented env var relocating a harness home dir, when one exists. */
+const HOME_ENV: Partial<Record<HarnessId, string>> = { kimi: "KIMI_CODE_HOME" };
+
+/**
+ * Resolve a harness's home config dir as an absolute path.
+ * @param id - Harness id.
+ * @param env - Environment (defaults to `process.env`).
+ * @param home - OS home dir (injectable for tests).
+ * @returns The override path when set, else `join(home, HOME_DIR[id])`.
+ */
+export function harnessHome(
+  id: string,
+  env: Record<string, string | undefined> = process.env,
+  home: string = homedir(),
+): string {
+  const key = HOME_ENV[id as HarnessId];
+  const override = key ? env[key] : undefined;
+  return override ?? join(home, HOME_DIR[id as HarnessId] ?? ".claude");
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+export * from "./env";
+export * from "./ttl";
+export * from "./limits";
+export * from "./layout";
+export * from "./dotenv";