@miroshnik/elves 0.0.0 → 2026.1018.1

package/bin/shims/timeout

@@ -0,0 +1,113 @@
+#!/usr/bin/env -S bun --no-env-file
+/**
+ * timeout — GNU coreutils `timeout` for a machine without it (macOS without coreutils). The SessionStart hook puts this
+ * directory at the end of the agent's Bash PATH (bin/elves.ts, `agentShellScript`), so a real `timeout` wins;
+ * tests/capabilities/agent-shell.
+ *
+ *   timeout [-s SIGNAL] [-k DURATION] [--preserve-status] [--foreground] [-v] DURATION COMMAND [ARG]...
+ *
+ * DURATION — a number with an optional suffix s, m, h, d; 0 — no limit. On expiry the command's process group gets
+ * SIGNAL (TERM by default): a grandchild that outlived the command would hold the call's output until its own end;
+ * with -k — KILL after DURATION more. Exit code: 124 — timed out (137 if KILL ended the command, as GNU), the
+ * command's own with --preserve-status; 125 — timeout itself failed; 126 — the command can't run; 127 — not found;
+ * otherwise the command's (128 + N for signal N). INT, TERM, HUP and QUIT that timeout gets go to the command.
+ * The `--no-env-file` flag in the shebang: Bun would load the project's env files and pass them to the command.
+ */
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+
+const USAGE = "Usage: timeout [-s SIGNAL] [-k DURATION] [--preserve-status] [--foreground] [-v] DURATION COMMAND [ARG]...";
+const SIGNALS: Record<string, number> = constants.signals;
+/** setTimeout fires at once past 2^31 - 1 ms (24.8 days): a longer limit waits that long — no agent call lasts it. */
+const MAX_DELAY = 2 ** 31 - 1;
+const UNITS: Record<string, number> = { "": 1, s: 1, m: 60, h: 3600, d: 86400 };
+
+function fail(message: string): never {
+  process.stderr.write(`timeout: ${message}\n`);
+  process.exit(125);
+}
+
+/** DURATION in milliseconds. */
+function duration(text: string) {
+  const m = /^(\d+(?:\.\d*)?|\.\d+)([smhd]?)$/.exec(text);
+  if (!m) fail(`invalid time interval '${text}'\n${USAGE}`);
+  return Math.min(Number(m[1]) * (UNITS[m[2] ?? ""] ?? 1) * 1000, MAX_DELAY);
+}
+
+/** A signal by name (KILL, SIGKILL, kill) or number. */
+function signal(text: string): NodeJS.Signals {
+  const name = /^\d+$/.test(text) ? Object.keys(SIGNALS).find((k) => SIGNALS[k] === Number(text)) : `SIG${text.toUpperCase().replace(/^SIG/, "")}`;
+  if (!name || !Object.hasOwn(SIGNALS, name)) fail(`${text}: invalid signal`);
+  return name as NodeJS.Signals;
+}
+
+const args = process.argv.slice(2);
+
+/** The value of an option before DURATION: `-s KILL`, `-sKILL`, `--signal KILL`, `--signal=KILL`; not it — undefined. */
+function value(short: string, long: string) {
+  const a = args[0] ?? "";
+  const inline = a.startsWith(`${long}=`) ? a.slice(long.length + 1) : a.startsWith(short) && a.length > short.length ? a.slice(short.length) : undefined;
+  if (inline !== undefined) return args.shift(), inline;
+  if (a !== short && a !== long) return undefined;
+  args.shift();
+  return args.shift() ?? fail(`option requires an argument -- '${short.slice(1)}'\n${USAGE}`);
+}
+
+let sig: NodeJS.Signals = "SIGTERM";
+let killAfter = 0;
+let preserve = false;
+let foreground = false;
+let verbose = false;
+// options go before DURATION, as with GNU: what follows belongs to the command
+for (let a = args[0]; a?.startsWith("-") && a !== "-"; a = args[0]) {
+  let v;
+  if (a === "--") {
+    args.shift();
+    break;
+  } else if ((v = value("-s", "--signal")) !== undefined) sig = signal(v);
+  else if ((v = value("-k", "--kill-after")) !== undefined) killAfter = duration(v);
+  else if (a === "--preserve-status") (preserve = true), args.shift();
+  else if (a === "--foreground") (foreground = true), args.shift();
+  else if (a === "-v" || a === "--verbose") (verbose = true), args.shift();
+  else if (a === "--help") process.stdout.write(USAGE + "\n"), process.exit(0);
+  else fail(`unrecognized option '${a}'\n${USAGE}`);
+}
+const [limitText, cmd, ...rest] = args;
+if (limitText === undefined || cmd === undefined) fail(`missing operand\n${USAGE}`);
+const limit = duration(limitText);
+
+// its own process group (a session) — the signal reaches the command's children too; --foreground — the command only
+const child = spawn(cmd, rest, { stdio: "inherit", detached: !foreground });
+let timedOut = false;
+const timers: ReturnType<typeof setTimeout>[] = [];
+
+function send(s: NodeJS.Signals) {
+  if (verbose && timedOut) process.stderr.write(`timeout: sending signal ${s.slice(3)} to command '${cmd}'\n`);
+  try {
+    if (foreground || child.pid === undefined) child.kill(s);
+    else process.kill(-child.pid, s);
+  } catch {
+    // the group is already gone
+  }
+}
+
+if (limit > 0) {
+  timers.push(
+    setTimeout(() => {
+      timedOut = true;
+      send(sig);
+      if (killAfter > 0) timers.push(setTimeout(() => send("SIGKILL"), killAfter));
+    }, limit),
+  );
+}
+for (const s of ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"] as const) process.on(s, () => send(s));
+
+child.on("error", (e: NodeJS.ErrnoException) => {
+  process.stderr.write(`timeout: failed to run command '${cmd}': ${e.code === "ENOENT" ? "No such file or directory" : e.message}\n`);
+  process.exit(e.code === "ENOENT" ? 127 : 126);
+});
+child.on("exit", (code, signalName) => {
+  for (const t of timers) clearTimeout(t);
+  const status = signalName ? 128 + (SIGNALS[signalName] ?? 0) : (code ?? 0);
+  process.exit(timedOut && !preserve && signalName !== "SIGKILL" ? 124 : status);
+});

package/claude/CLAUDE.md

@@ -0,0 +1,71 @@
+# Claude Code
+
+Shared rules — `AGENTS.md`; here — only what Claude Code has. `install -g`
+puts both into `~/.claude/rules/` (`elves.md`, `elves-claude.md`): loaded in
+every project, whatever its `CLAUDE.md`.
+
+- Session transcripts (`~/.claude/projects/<path-with-dashes>*/`) are the
+  source of actuals for the `est` skill; `~/.claude/settings.json` must have
+  `"cleanupPeriodDays": 365`, otherwise history is cleaned before it's needed.
+- The app's worktree names the branch `claude/<slug>-<hash>` — it is renamed
+  when the task is taken: `github task status <N> "In progress" --branch
+  <type>/<N>-<slug>` (a bare `git branch -m` fails on `.git/config` locked by
+  a parallel worktree and leaves the upstream behind). The session panel
+  (branch, diff to `main`, "Create PR") reads git, not GitHub: after a merge
+  it is accurate once the checkout is on `origin/main` (`github task close`
+  moves it).
+- Auto-fix (CI monitor) — off: its conflict event wants the base merged in,
+  breaking the rebase merge. After `gh pr create` — `set_monitor` with
+  `auto_fix: false` and the PR's url; a conflict — rebase onto a fresh
+  `origin/main`; an executor's PR — its executor's (`docs/pr-checks.md`,
+  "Auto-fix"). Checks and the deploy — `ci-wait` as a background command,
+  its completion wakes the session; no `Monitor`, watcher loop or
+  `ScheduleWakeup` on top: an armed wakeup keeps `archive_session` refused
+  even after `stop`.
+- Merge in auto mode — `gh pr merge <N> --rebase` as a separate call, without
+  `cd`, `|`, `;`: otherwise the `Bash(gh pr merge *)` rule (set by the owner)
+  won't match and the classifier rejects the merge.
+- `install -g` puts a `SessionStart` hook into `~/.claude/settings.json`
+  (`startup|resume|clear`): `check --hook` — the machine (canon, skills, hook)
+  and the project's flow with its mode and language (`AGENTS.md`, "First step
+  of a session") into the start of the context: a thin project's lag —
+  `update` in the session's task, a copy — the canon twice and its move task,
+  no flow — install it; a
+  session with a pinned task (a resume after the app restarted) gets the wait
+  to restart — `github task resume` with the session id from the hook's input.
+  The hook always exits 0 (else Claude Code drops its output), timeout 60 s.
+  No hook output in context — run `check` by hand. The hook also writes the
+  agent's Bash environment to `$CLAUDE_ENV_FILE`: zsh passes a glob without
+  matches and `====` as is, `timeout` works without coreutils; the
+  «agent Bash: not set up» line — it didn't, follow the line.
+- `set_session_title` renames the session; in auto mode `archive_session`
+  with `self` archives it, ending the conversation: the last action, after
+  the "can be closed" line. Before it — `TaskStop` for each own
+  background task still running: a live one gives "still has live work".
+  Refused after that — don't retry: the owner archives from the sidebar.
+- Skills — the machine's `~/.claude/skills/<name>` (symlinks to
+  `~/.agents/skills/<name>`), a thin project has no others; the skill
+  directory is `${CLAUDE_SKILL_DIR}`; a same-named machine skill wins over a
+  project's. `SKILL.md` frontmatter also reads `when_to_use`,
+  `argument-hint`, `allowed-tools`.
+- The Bash sandbox: `gh` in it fails on TLS (`x509: OSStatus -26276`). A
+  skill script that calls `gh` (`github`, `est`, `dashboard`, `spec-run`) —
+  at once a separate call with `dangerouslyDisableSandbox`: no
+  `excludedCommands` entry takes `bun <file>` out. Entries `gh *` and `bash
+  <path>/wait-ci.sh *` (`ci-wait`) do — the owner's step; without them — the
+  same separate call. The `task-env` skill, section "Docker and the sandbox".
+- A subagent that writes gets `isolation: worktree`: an isolated session
+  doesn't write into others' worktrees, an agent without it inherits the
+  parent's isolation. An agent cut off (a limit, a dropped session) leaves
+  uncommitted work in its worktree — `git status` there before resuming;
+  after a base change — dependencies from the lockfile, else typecheck runs
+  on old packages.
+- In a cloud session (claude.ai/code) the cloud assigns the branch — rename
+  it or push to another one only with the user's permission
+  (`docs/cloud-sessions.md`).
+- Another task isn't a session card (`spawn_task`, `start_session`): the
+  question «queue #M?», on "yes" its executor — `Agent` with `isolation:
+  "worktree"`, `run_in_background: true` and the prompt `github` printed.
+  The executor isn't `TaskStop`ped: the last line — after its answer.
+- An Elves clone: `install -g --link` links `~/.claude/rules/elves*.md` to
+  it, its `.claude/CLAUDE.md` keeps the root `AGENTS.md` from loading twice.