harnery 0.36.0 → 0.38.0

package/src/lib/durable-job.ts

@@ -0,0 +1,407 @@
+// Durable job records: a small on-disk representation of "a job that outlives
+// the client that launched it". A supervisor process owns the record; a client
+// only reads it. A bridge drop, a closed terminal, or a killed client
+// therefore interrupts the *view* of the job, never the job itself.
+//
+// Layout, under a caller-supplied base directory:
+//
+//   <base>/jobs/<job_id>/job.json      immutable description (argv, cwd, resource)
+//   <base>/jobs/<job_id>/status.json   mutable state, rewritten atomically
+//   <base>/jobs/<job_id>/job.log       merged child stdout + stderr
+//
+// Classification is fail-closed, mirroring qa-status: liveness is proven by the
+// PID, never assumed from the status document. A non-terminal state whose PID
+// is dead classifies as "dead", never as "running".
+//
+// Toolkit tier: this module must not import src/core (layering check).
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+export const DURABLE_JOB_SCHEMA_VERSION = 1;
+
+/** How often the supervisor rewrites status.json while a job runs. */
+export const DURABLE_JOB_HEARTBEAT_MS = 15_000;
+
+/** A running job whose heartbeat is older than this earns a staleness warning,
+ * but stays "running" while its PID is alive. */
+export const DURABLE_JOB_HEARTBEAT_STALE_MS = 120_000;
+
+export const DURABLE_JOB_DOCUMENT_FILENAME = "job.json";
+export const DURABLE_JOB_STATUS_FILENAME = "status.json";
+export const DURABLE_JOB_LOG_FILENAME = "job.log";
+
+const JOBS_DIRNAME = "jobs";
+
+/** States a supervisor writes. "completed" is the only terminal one. */
+export type DurableJobState = "launching" | "queued" | "running" | "completed";
+
+/** States a reader can observe. "dead" is derived, never written. */
+export type DurableJobObservedState = DurableJobState | "dead";
+
+const WRITTEN_STATES = new Set<string>(["launching", "queued", "running", "completed"]);
+
+export interface DurableJobDocument {
+  schema_version: number;
+  job_id: string;
+  /** Admission resource the job queues on. */
+  resource: string;
+  /** Concurrent holders allowed on that resource. */
+  capacity: number;
+  /** Human-readable description shown in listings. */
+  label: string;
+  /** Argument vector of the wrapped command; argv[0] is the executable. */
+  argv: string[];
+  /** Directory the wrapped command runs in. */
+  cwd: string;
+  created_at: string;
+}
+
+export interface DurableJobStatus {
+  schema_version: number;
+  job_id: string;
+  /** PID of the supervisor, not of the wrapped command. */
+  pid: number;
+  state: DurableJobState;
+  started_at: string;
+  updated_at: string;
+  /** Present while the supervisor waits for an admission slot. */
+  queue?: { resource: string; waiting_since: string };
+  exit_code?: number | null;
+  signal?: string | null;
+}
+
+export interface DurableJobReport {
+  state: DurableJobObservedState;
+  /** The job reached "completed"; exit_code and signal are final. */
+  terminal: boolean;
+  job_id: string | null;
+  pid: number | null;
+  resource: string | null;
+  label: string | null;
+  argv: string[] | null;
+  exit_code: number | null;
+  signal: string | null;
+  created_at: string | null;
+  started_at: string | null;
+  updated_at: string | null;
+  /** now minus status.updated_at; null without a parseable heartbeat. */
+  heartbeat_age_ms: number | null;
+  queue?: { resource: string; waiting_since: string };
+  job_dir: string;
+  log_path: string;
+  warnings: string[];
+}
+
+export interface DurableJobDeps {
+  /** PID liveness probe (injectable for tests). Default: process.kill(pid, 0). */
+  pidAlive?: (pid: number) => boolean;
+  /** Evaluation instant in epoch milliseconds. Default: Date.now(). */
+  now?: () => number;
+}
+
+export type DurableJobClassification =
+  | { ok: true; report: DurableJobReport }
+  | { ok: false; error: string };
+
+export interface DurableJobListEntry {
+  job_id: string;
+  job_dir: string;
+  created_at: string | null;
+  document: DurableJobDocument | null;
+  report: DurableJobReport | null;
+  /** Set when the directory exists but its status document is unusable. */
+  error?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Default PID liveness probe. EPERM counts as alive; only ESRCH is dead. */
+function defaultPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    return (err as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+/** Directory holding every job record under a base directory. */
+export function jobsRoot(base: string): string {
+  return join(resolve(base), JOBS_DIRNAME);
+}
+
+/** Directory of one job record. Does not create it. */
+export function jobDirFor(base: string, jobId: string): string {
+  return join(jobsRoot(base), jobId);
+}
+
+/** Create (idempotently) the directory for one job and return its path. */
+export function createJobDir(base: string, jobId: string): string {
+  const dir = jobDirFor(base, jobId);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function jobLogPath(jobDir: string): string {
+  return join(resolve(jobDir), DURABLE_JOB_LOG_FILENAME);
+}
+
+function writeAtomic(path: string, body: string): void {
+  const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(tmp, body);
+  renameSync(tmp, path);
+}
+
+/** Write the immutable job description. */
+export function writeJobDocument(jobDir: string, document: DurableJobDocument): void {
+  writeAtomic(
+    join(resolve(jobDir), DURABLE_JOB_DOCUMENT_FILENAME),
+    `${JSON.stringify(document, null, 2)}\n`,
+  );
+}
+
+/** Replace the status document atomically, so a reader never sees a torn file. */
+export function writeJobStatus(jobDir: string, status: DurableJobStatus): void {
+  writeAtomic(
+    join(resolve(jobDir), DURABLE_JOB_STATUS_FILENAME),
+    `${JSON.stringify(status, null, 2)}\n`,
+  );
+}
+
+function readJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+/** Read the job description, or null when it is missing or unusable. */
+export function readJobDocument(jobDir: string): DurableJobDocument | null {
+  const path = join(resolve(jobDir), DURABLE_JOB_DOCUMENT_FILENAME);
+  let parsed: unknown;
+  try {
+    parsed = readJson(path);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (typeof parsed.job_id !== "string") return null;
+  return {
+    schema_version:
+      typeof parsed.schema_version === "number"
+        ? parsed.schema_version
+        : DURABLE_JOB_SCHEMA_VERSION,
+    job_id: parsed.job_id,
+    resource: typeof parsed.resource === "string" ? parsed.resource : "",
+    capacity: typeof parsed.capacity === "number" ? parsed.capacity : 1,
+    label: typeof parsed.label === "string" ? parsed.label : "",
+    argv: Array.isArray(parsed.argv)
+      ? parsed.argv.filter((a): a is string => typeof a === "string")
+      : [],
+    cwd: typeof parsed.cwd === "string" ? parsed.cwd : "",
+    created_at: typeof parsed.created_at === "string" ? parsed.created_at : "",
+  };
+}
+
+/** Read the status document, or null when it is missing or unusable. */
+export function readJobStatus(jobDir: string): DurableJobStatus | null {
+  const path = join(resolve(jobDir), DURABLE_JOB_STATUS_FILENAME);
+  let parsed: unknown;
+  try {
+    parsed = readJson(path);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (typeof parsed.job_id !== "string") return null;
+  if (typeof parsed.state !== "string" || !WRITTEN_STATES.has(parsed.state)) return null;
+  const queue = parsed.queue;
+  return {
+    schema_version:
+      typeof parsed.schema_version === "number"
+        ? parsed.schema_version
+        : DURABLE_JOB_SCHEMA_VERSION,
+    job_id: parsed.job_id,
+    pid: typeof parsed.pid === "number" ? parsed.pid : 0,
+    state: parsed.state as DurableJobState,
+    started_at: typeof parsed.started_at === "string" ? parsed.started_at : "",
+    updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : "",
+    ...(isRecord(queue) &&
+    typeof queue.resource === "string" &&
+    typeof queue.waiting_since === "string"
+      ? { queue: { resource: queue.resource, waiting_since: queue.waiting_since } }
+      : {}),
+    ...(typeof parsed.exit_code === "number" || parsed.exit_code === null
+      ? { exit_code: parsed.exit_code as number | null }
+      : {}),
+    ...(typeof parsed.signal === "string" || parsed.signal === null
+      ? { signal: parsed.signal as string | null }
+      : {}),
+  };
+}
+
+/**
+ * Classify one job directory, fail-closed. "completed" is terminal and carries
+ * the wrapped command's exit code. Any other written state is trusted only
+ * while the supervisor PID is alive; otherwise the job is "dead" — the record
+ * outlived the process that owned it.
+ */
+export function classifyJob(jobDir: string, deps: DurableJobDeps = {}): DurableJobClassification {
+  const isAlive = deps.pidAlive ?? defaultPidAlive;
+  const nowMs = deps.now ? deps.now() : Date.now();
+  const abs = resolve(jobDir);
+  if (!existsSync(abs)) return { ok: false, error: `no such job directory: ${abs}` };
+
+  const statusPath = join(abs, DURABLE_JOB_STATUS_FILENAME);
+  if (!existsSync(statusPath)) {
+    return {
+      ok: false,
+      error: `${abs} carries no ${DURABLE_JOB_STATUS_FILENAME}: not a job directory`,
+    };
+  }
+  const status = readJobStatus(abs);
+  if (!status) {
+    return { ok: false, error: `${statusPath} is not a readable job status document` };
+  }
+  const document = readJobDocument(abs);
+
+  let heartbeatAgeMs: number | null = null;
+  const updatedMs = Date.parse(status.updated_at);
+  if (!Number.isNaN(updatedMs)) heartbeatAgeMs = Math.max(0, nowMs - updatedMs);
+
+  const base = {
+    job_id: status.job_id,
+    pid: status.pid > 0 ? status.pid : null,
+    resource: document?.resource ?? null,
+    label: document?.label ?? null,
+    argv: document?.argv ?? null,
+    created_at: document?.created_at ?? null,
+    started_at: status.started_at || null,
+    updated_at: status.updated_at || null,
+    heartbeat_age_ms: heartbeatAgeMs,
+    job_dir: abs,
+    log_path: jobLogPath(abs),
+  };
+
+  if (status.state === "completed") {
+    return {
+      ok: true,
+      report: {
+        ...base,
+        state: "completed",
+        terminal: true,
+        exit_code: status.exit_code ?? null,
+        signal: status.signal ?? null,
+        warnings: [],
+      },
+    };
+  }
+
+  if (!(status.pid > 0 && isAlive(status.pid))) {
+    return {
+      ok: true,
+      report: {
+        ...base,
+        state: "dead",
+        terminal: false,
+        exit_code: null,
+        signal: null,
+        ...(status.queue ? { queue: status.queue } : {}),
+        warnings: [],
+      },
+    };
+  }
+
+  const warnings: string[] = [];
+  if (
+    status.state === "running" &&
+    heartbeatAgeMs !== null &&
+    heartbeatAgeMs > DURABLE_JOB_HEARTBEAT_STALE_MS
+  ) {
+    warnings.push(
+      `heartbeat stale: last update ${Math.round(heartbeatAgeMs / 1000)}s ago ` +
+        `(threshold ${DURABLE_JOB_HEARTBEAT_STALE_MS / 1000}s), but pid ${status.pid} is alive`,
+    );
+  }
+  return {
+    ok: true,
+    report: {
+      ...base,
+      state: status.state,
+      terminal: false,
+      exit_code: null,
+      signal: null,
+      ...(status.queue ? { queue: status.queue } : {}),
+      warnings,
+    },
+  };
+}
+
+/**
+ * Every job record under a base directory, newest first. Ordering keys on the
+ * description's created_at, falling back to the status document's started_at,
+ * then to the directory name, so a record missing its description still lists.
+ */
+export function listJobs(base: string, deps: DurableJobDeps = {}): DurableJobListEntry[] {
+  const root = jobsRoot(base);
+  let names: string[];
+  try {
+    names = readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+  const entries: { entry: DurableJobListEntry; sortKey: number }[] = [];
+  for (const name of names) {
+    const dir = join(root, name);
+    const document = readJobDocument(dir);
+    const classified = classifyJob(dir, deps);
+    const createdAt =
+      document?.created_at || (classified.ok ? classified.report.started_at : null) || null;
+    const parsed = createdAt !== null ? Date.parse(createdAt) : Number.NaN;
+    entries.push({
+      entry: {
+        job_id: document?.job_id ?? name,
+        job_dir: dir,
+        created_at: createdAt,
+        document,
+        report: classified.ok ? classified.report : null,
+        ...(classified.ok ? {} : { error: classified.error }),
+      },
+      sortKey: Number.isNaN(parsed) ? 0 : parsed,
+    });
+  }
+  entries.sort((a, b) => {
+    if (b.sortKey !== a.sortKey) return b.sortKey - a.sortKey;
+    return b.entry.job_id.localeCompare(a.entry.job_id);
+  });
+  return entries.map((item) => item.entry);
+}
+
+/** Describe a job's outcome as a process exit code: the wrapped command's own
+ * code, 1 when it died on a signal, 4 when the record is dead. */
+export function jobExitCode(report: DurableJobReport): number {
+  if (report.state === "dead") return 4;
+  if (!report.terminal) return 5;
+  if (report.signal !== null) return 1;
+  return report.exit_code ?? 1;
+}
+
+/** Format a duration the way the status commands do. */
+export function formatJobAge(ms: number): string {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  if (minutes < 60) return `${minutes}m ${totalSeconds % 60}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}

package/src/lib/http/client.ts

@@ -1,4 +1,9 @@
-import type { Cookie, CookieJar } from "../cookies/index.ts";
+import {
+  applyExtraCookies,
+  type Cookie,
+  type CookieJar,
+  type ExtraCookies,
+} from "../cookies/index.ts";
 
 /**
  * Simple cookie-aware HTTP client.
@@ -39,6 +44,12 @@ export interface FetchOptions<TResponseType extends FetchResponseType = "text">
    * only land when the key isn't already set.
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Optional callback that returns extra cookies to persist into `jar`
+   * before the Cookie header is built. Ignored when no jar is passed
+   * (`--no-cookies`). Must stay synchronous.
+   */
+  extraCookies?: ExtraCookies;
   /** Response body representation. Default `text`; use `bytes` for lossless file output. */
   responseType?: TResponseType;
 }
@@ -72,6 +83,7 @@ export async function fetchWithJar<TResponseType extends FetchResponseType = "te
   const headers: Record<string, string> = { ...(opts.headers ?? {}) };
 
   if (opts.jar) {
+    applyExtraCookies(url, opts.jar, opts.extraCookies);
     const cookieHeader = opts.jar.header(url);
     if (cookieHeader && !headers.Cookie && !headers.cookie) {
       headers.Cookie = cookieHeader;

package/src/lib/instructions/apply.ts

@@ -7,13 +7,15 @@
  * writes, and deletes so init/deinit stay thin and this stays integration-
  * testable against a temp dir.
  *
- * Two files, one dir:
+ * Three files, one dir:
  *   - `AGENTS.md` — the always-on orientation block (a managed region; the
  *     consumer owns the rest of the file).
  *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.cursor/rules/harnery-turn-ritual.mdc` — cursor only; an Always Apply
+ *     rule that makes the Stop-enforced status footer visible in reply text.
  *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
  *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
  *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
@@ -29,7 +31,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { stripJsonComments } from "../../core/config.ts";
+import { endOfTurnStatusCommand, stripJsonComments } from "../../core/config.ts";
 import { readHostAddendum } from "./host-addendum.ts";
 import {
   checkOwnedSkill,
@@ -37,6 +39,7 @@ import {
   isOwnedFile,
   type ManagedStatus,
   removeRegion,
+  shortHash,
   spliceRegion,
 } from "./splice.ts";
 import {
@@ -50,6 +53,7 @@ import {
 
 const AGENTS_FILE = "AGENTS.md";
 const CLAUDE_FILE = "CLAUDE.md";
+const CURSOR_RULE_FILE = join(".cursor", "rules", "harnery-turn-ritual.mdc");
 const ADAPTER_SKILLS_DIR: Readonly<Record<string, string>> = {
   "claude-code": join(".claude", "skills"),
   cursor: join(".agents", "skills"),
@@ -71,6 +75,39 @@ function skillBody(render: (bin: string) => string, binName: string): string {
   return content.slice(content.indexOf("-->") + 3).trim();
 }
 
+function cursorRuleBody(projectRoot: string, binName: string): string {
+  const statusCommand = endOfTurnStatusCommand(projectRoot);
+  return [
+    "# Harnery turn ritual",
+    "",
+    "On every turn that uses tools:",
+    "",
+    `1. Run \`${binName} agents set-task "<short focus>"\` during the turn, even when the focus is unchanged.`,
+    `2. Make \`${statusCommand}\` your final tool call.`,
+    "3. Append that command's stdout verbatim in a fenced code block at the bottom of the same substantive reply.",
+    "",
+    "Cursor Stop enforces all three signals. A missing signal produces one follow-up that names every repair needed.",
+  ].join("\n");
+}
+
+function cursorRuleContent(projectRoot: string, binName: string): string {
+  const body = cursorRuleBody(projectRoot, binName);
+  const marker =
+    `<!-- harnery:generated cursor-turn-ritual v=${shortHash(body)}; machine-owned; ` +
+    `regenerated by \`${binName} init\`, removed by \`${binName} deinit\`. ` +
+    "Edit the harnery template, not this file. -->";
+  return [
+    "---",
+    "description: Harnery end-of-turn coordination ritual",
+    "alwaysApply: true",
+    "---",
+    marker,
+    "",
+    body,
+    "",
+  ].join("\n");
+}
+
 /** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
 export function readSkillsExclude(projectRoot: string): Set<string> {
   const p = join(projectRoot, ".harnery", "config.jsonc");
@@ -203,6 +240,27 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
     }
   }
 
+  // ── Cursor Always Apply rule ────────────────────────────────────────────
+  if (opts.adapter === "cursor") {
+    const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+    const content = cursorRuleContent(projectRoot, opts.binName);
+    const before = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : null;
+    if (before === content) {
+      actions.push(`· ${CURSOR_RULE_FILE} already current`);
+    } else if (before !== null && !isOwnedFile(before)) {
+      warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+    } else {
+      if (!opts.dryRun) {
+        mkdirSync(dirname(rulePath), { recursive: true });
+        writeFileSync(rulePath, content);
+      }
+      const fresh = before === null;
+      actions.push(
+        `${fresh ? "+" : "~"} ${verbed(fresh ? "write" : "update", fresh ? "wrote" : "updated")} ${CURSOR_RULE_FILE}`,
+      );
+    }
+  }
+
   // ── shipped skills ───────────────────────────────────────────────────────
   if (skillsDir) {
     const exclude = readSkillsExclude(projectRoot);
@@ -301,6 +359,18 @@ export function removeInstructions(projectRoot: string, opts: RemoveOpts): Apply
     }
   }
 
+  if (opts.adapter === "cursor") {
+    const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+    if (existsSync(rulePath)) {
+      if (!isOwnedFile(readFileSync(rulePath, "utf8"))) {
+        warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+      } else {
+        if (!opts.dryRun) rmSync(rulePath);
+        actions.push(`+ ${opts.dryRun ? "would delete" : "deleted"} ${CURSOR_RULE_FILE}`);
+      }
+    }
+  }
+
   // ── shipped skills ───────────────────────────────────────────────────────
   if (skillsDir) {
     for (const skill of SKILLS) {
@@ -384,6 +454,15 @@ export function checkInstructions(
         note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
       }
     }
+
+    if (opts.adapter === "cursor") {
+      const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+      const content = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : "";
+      note(
+        `${CURSOR_RULE_FILE} rule`,
+        checkOwnedSkill(content, cursorRuleBody(projectRoot, opts.binName)),
+      );
+    }
   } catch (err) {
     errored = true;
     issues.push(`error reading instructions state: ${(err as Error).message}`);

package/src/lib/instructions/templates.ts

@@ -135,6 +135,12 @@ coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
 
+**Messaging another agent.** \`${b} agents ping <name> "<message>"\` reaches an
+agent by name whether or not they are running: a live agent sees it on their next
+prompt, and a dormant name holds it until a session of that name next starts.
+Send it as your first and only step. Do not check who is live first, and do not
+hunt for somewhere else to leave it. Only a never-used name is refused.
+
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
 \`${b} journal read\` reads yours, \`${b} journal read --name <peer>\` reads a peer's.
@@ -276,10 +282,13 @@ auto-route into contribute.
 ## Create (\`create <objective>\`)
 
 The web UI is the member + steward picker; don't create from the CLI (that skips
-the steward choice). Emit the link with the objective URL-encoded:
+the steward choice). Read the dashboard base URL from the active Harnery web
+status or start output, which resolves the project's configured \`web.port\`.
+Append the URL-encoded objective to this path; never assume a port or reuse a
+dashboard URL from another project:
 
 \`\`\`
-http://localhost:4276/councils/new?objective=<encoded>
+<configured-dashboard-base-url>/councils/new?objective=<encoded>
 \`\`\`
 
 If the dev server isn't up, start it with \`${b} web up\`.