harnery 0.45.1 → 0.46.0

package/src/lib/browser/windows-login-sync.ts

@@ -0,0 +1,275 @@
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { Cookie } from "../cookies/client.ts";
+import { CookieJar, mergeCookies } from "../cookies/index.ts";
+import type { WindowsChromeHarvest } from "./windows-chrome.ts";
+
+/**
+ * Keep the shared cookie store current with the WSL sign-in profile.
+ *
+ * Under WSL, `browse --login` signs in through the Windows host's Chrome on a
+ * dedicated profile and copies that site's cookies into the cookie store when
+ * the window closes. People also keep that profile open as an ordinary
+ * browser and sign in to other sites there later. Nothing copies those
+ * sign-ins when the window is closed outside a waiting `--login` run, so a
+ * later headless run would show the site signed out.
+ *
+ * Before a headless run, this module compares the profile's cookie database
+ * modification time with the time recorded at the last copy for the run's
+ * domain. When the profile changed and no Chrome is running on it, the
+ * domain's cookies are read (the same headless read `--login` uses) and
+ * merged into the store. A profile that is open is never touched. A small
+ * owner-only state file next to the store records, per domain, the database
+ * time and a fingerprint of the cookies last read. When a read returns the
+ * same cookies as last time, nothing is merged, so cookies a headless run
+ * refreshed in the store are not replaced with the profile's older copies.
+ */
+
+export interface DomainSyncRecord {
+  /** When the profile's cookies for the domain were last read. */
+  syncedAt: string;
+  /** Cookie database modification time right after that read. */
+  cookieDbMtimeMs: number;
+  /** SHA-256 over the cookies read, so an unchanged read merges nothing. */
+  fingerprint: string;
+  /** Number of cookies read. */
+  cookies: number;
+}
+
+export interface LoginSyncState {
+  version: 1;
+  domains: Record<string, DomainSyncRecord>;
+}
+
+/** The sync-state file for a cookie store: `<store>.login-sync.json`, beside it. */
+export function loginSyncStatePath(storePath: string): string {
+  const name = basename(storePath).replace(/\.json$/i, "");
+  return join(dirname(storePath), `${name}.login-sync.json`);
+}
+
+export function readLoginSyncState(statePath: string): LoginSyncState {
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, "utf8")) as Partial<LoginSyncState>;
+    if (parsed && parsed.version === 1 && parsed.domains && typeof parsed.domains === "object") {
+      return { version: 1, domains: parsed.domains };
+    }
+  } catch {
+    // Missing or unreadable state means nothing has been copied yet.
+  }
+  return { version: 1, domains: {} };
+}
+
+/** Write the state file owner-only, replacing it atomically. */
+export function writeLoginSyncState(statePath: string, state: LoginSyncState): void {
+  mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+  const tmp = `${statePath}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, statePath);
+}
+
+/** Order-independent fingerprint of a cookie set. Values are hashed, never stored. */
+export function cookieFingerprint(cookies: Cookie[]): string {
+  const rows = cookies
+    .map((c) => JSON.stringify([c.name, c.domain, c.path, c.value, c.expires]))
+    .sort();
+  return createHash("sha256").update(rows.join("\n")).digest("hex");
+}
+
+export type LoginSyncDecision =
+  /** No cookie database: the profile has never been used. */
+  | "no-profile"
+  /** The database has not changed since the last read for this domain. */
+  | "current"
+  /** The database is newer, but Chrome is open on the profile. */
+  | "open"
+  /** The database is newer (or the read is forced) and the profile is closed. */
+  | "sync";
+
+/**
+ * Decide what to do before reading. `running` is consulted only when the
+ * database is newer, since checking for Chrome costs a PowerShell call.
+ */
+export function decideLoginSync(input: {
+  cookieDbMtimeMs: number | undefined;
+  record: DomainSyncRecord | undefined;
+  running: () => boolean;
+  force?: boolean;
+}): LoginSyncDecision {
+  if (input.cookieDbMtimeMs === undefined) return "no-profile";
+  if (!input.force && input.record && input.cookieDbMtimeMs <= input.record.cookieDbMtimeMs)
+    return "current";
+  return input.running() ? "open" : "sync";
+}
+
+export interface LoginSyncDeps {
+  /** Newest modification time of the profile's cookie database, or `undefined`. */
+  cookieDbMtimeMs: () => number | undefined;
+  /** Ids of Chrome processes running on the profile. */
+  profileProcesses: () => number[];
+  /** Read the profile's cookies for `domain`; the profile must be closed. */
+  harvest: (domain: string) => WindowsChromeHarvest;
+  now?: () => Date;
+}
+
+export interface LoginSyncResult {
+  status: "no-profile" | "current" | "open" | "busy" | "synced" | "unchanged";
+  domain: string;
+  /** Cookies read from the profile (0 when nothing was read). */
+  cookies: number;
+  /** Cookies merged into the store (0 unless `synced`). */
+  merged: number;
+  sessionCookies: number;
+  /** Cookie names merged, sorted. Never values. */
+  names: string[];
+  /** Chrome process ids on the profile when `open`. */
+  processes: number[];
+}
+
+/**
+ * Copy the profile's cookies for `domain` into the store when the profile
+ * changed since the last copy and is closed. `force` skips the time check
+ * and merges whatever is read. Throws only on read failures; the caller
+ * decides whether that is a warning.
+ */
+export function syncLoginCookies(input: {
+  domain: string;
+  storePath: string;
+  deps: LoginSyncDeps;
+  force?: boolean;
+}): LoginSyncResult {
+  const { domain, storePath, deps } = input;
+  const base: LoginSyncResult = {
+    status: "current",
+    domain,
+    cookies: 0,
+    merged: 0,
+    sessionCookies: 0,
+    names: [],
+    processes: [],
+  };
+  const statePath = loginSyncStatePath(storePath);
+  const state = readLoginSyncState(statePath);
+  const record = state.domains[domain];
+  let processes: number[] = [];
+  const decision = decideLoginSync({
+    cookieDbMtimeMs: deps.cookieDbMtimeMs(),
+    record,
+    force: input.force,
+    running: () => {
+      processes = deps.profileProcesses();
+      return processes.length > 0;
+    },
+  });
+  if (decision === "no-profile") return { ...base, status: "no-profile" };
+  if (decision === "current") return base;
+  if (decision === "open") return { ...base, status: "open", processes };
+
+  const release = acquireSyncLock(statePath);
+  if (!release) return { ...base, status: "busy" };
+  try {
+    const { cookies } = deps.harvest(domain);
+    const fingerprint = cookieFingerprint(cookies);
+    const changed = input.force || !record || record.fingerprint !== fingerprint;
+    let merged: Cookie[] = [];
+    if (changed && cookies.length > 0) {
+      const jar = new CookieJar({ path: storePath, source: "harn-browse" });
+      jar.save(mergeCookies(jar.load(), cookies));
+      merged = cookies;
+    }
+    const after = readLoginSyncState(statePath);
+    after.domains[domain] = {
+      syncedAt: (deps.now?.() ?? new Date()).toISOString(),
+      cookieDbMtimeMs: deps.cookieDbMtimeMs() ?? 0,
+      fingerprint,
+      cookies: cookies.length,
+    };
+    writeLoginSyncState(statePath, after);
+    return {
+      ...base,
+      status: merged.length > 0 ? "synced" : "unchanged",
+      cookies: cookies.length,
+      merged: merged.length,
+      sessionCookies: merged.filter((c) => c.expires <= 0).length,
+      names: [...new Set(merged.map((c) => c.name))].sort(),
+    };
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Record a read that happened elsewhere (the `--login` flow), so the next
+ * headless run does not read the same cookies again.
+ */
+export function recordLoginSync(input: {
+  domain: string;
+  storePath: string;
+  cookies: Cookie[];
+  cookieDbMtimeMs: number | undefined;
+  now?: Date;
+}): void {
+  const statePath = loginSyncStatePath(input.storePath);
+  const state = readLoginSyncState(statePath);
+  state.domains[input.domain] = {
+    syncedAt: (input.now ?? new Date()).toISOString(),
+    cookieDbMtimeMs: input.cookieDbMtimeMs ?? 0,
+    fingerprint: cookieFingerprint(input.cookies),
+    cookies: input.cookies.length,
+  };
+  writeLoginSyncState(statePath, state);
+}
+
+/** Newest mtime among a profile's cookie database locations, or `undefined`. */
+export function profileCookieDbMtimeMs(
+  profileLinux: string,
+  stat: (path: string) => number | undefined = fileMtimeMs,
+): number | undefined {
+  const times = [
+    join(profileLinux, "Default", "Network", "Cookies"),
+    join(profileLinux, "Default", "Cookies"),
+  ]
+    .map((path) => stat(path))
+    .filter((t): t is number => t !== undefined);
+  return times.length > 0 ? Math.max(...times) : undefined;
+}
+
+function fileMtimeMs(path: string): number | undefined {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+const LOCK_STALE_MS = 3 * 60_000;
+
+/**
+ * One read at a time: a second headless Chrome on the profile would refuse
+ * to start. A lock older than three minutes is treated as abandoned.
+ */
+function acquireSyncLock(statePath: string): (() => void) | null {
+  const lockPath = `${statePath}.lock`;
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      closeSync(openSync(lockPath, "wx", 0o600));
+      return () => rmSync(lockPath, { force: true });
+    } catch {
+      const age = existsSync(lockPath) ? Date.now() - (fileMtimeMs(lockPath) ?? 0) : 0;
+      if (age < LOCK_STALE_MS) return null;
+      rmSync(lockPath, { force: true });
+    }
+  }
+  return null;
+}

package/src/lib/cookies/client.ts

@@ -284,9 +284,9 @@ export class CookieJar {
   }
 
   /**
-   * Read + filter helper. Drops expired cookies. Optional domain filter
-   * uses the same `domainMatches` logic Playwright/CDP do (leading dot
-   * means subdomain match).
+   * Read + filter helper. Drops expired cookies. The optional domain filter
+   * uses `domainMatches` (equal host or any subdomain); it is a query, not a
+   * delivery rule. `header(url)` uses the stricter `cookieSendsToHost`.
    */
   list(filter: { domain?: string } = {}): Cookie[] {
     const store = this.load();
@@ -451,14 +451,62 @@ export function mergeCookies(store: CookieStore, incoming: Cookie[]): CookieStor
   return { ...store, cookies: Array.from(map.values()) };
 }
 
-/** RFC 6265 domain match. Leading dot in cookie domain means subdomain match. */
+/**
+ * Filter-style domain match used by `list({ domain })` and `clear({ domain })`:
+ * a cookie domain "matches" a hostname when they are equal or the hostname is
+ * a subdomain of it, whether or not the cookie is host-only. Never use this to
+ * decide whether a cookie may be SENT to a host; use `cookieSendsToHost`.
+ */
 export function domainMatches(cookieDomain: string, hostname: string): boolean {
-  const cd = cookieDomain.startsWith(".") ? cookieDomain.slice(1) : cookieDomain;
-  if (hostname === cd) return true;
-  if (hostname.endsWith(`.${cd}`)) return true;
+  const cd = (cookieDomain.startsWith(".") ? cookieDomain.slice(1) : cookieDomain).toLowerCase();
+  const host = hostname.toLowerCase();
+  if (host === cd) return true;
+  if (host.endsWith(`.${cd}`)) return true;
   return false;
 }
 
+/**
+ * RFC 6265 delivery rule. A cookie domain with a leading dot is a domain
+ * cookie and goes to the domain and every subdomain. A cookie domain without
+ * one is host-only (how CDP, Playwright and `Set-Cookie` without `Domain`
+ * record it) and goes to that exact host and nowhere else.
+ */
+export function cookieSendsToHost(cookieDomain: string, hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  if (cookieDomain.startsWith(".")) return domainMatches(cookieDomain, host);
+  return cookieDomain.toLowerCase() === host;
+}
+
+/**
+ * Cookie-prefix rules (RFC 6265bis). `__Secure-` needs Secure; `__Host-` also
+ * needs Path=/ and no Domain attribute, which a jar records as a host-only
+ * domain (no leading dot). Browsers refuse a violating cookie, so the jar
+ * never stores one and the browser injector never hands one to Chromium.
+ */
+export function violatesCookiePrefix(
+  cookie: Pick<Cookie, "name" | "domain" | "path" | "secure">,
+): boolean {
+  if (cookie.name.startsWith("__Secure-") && !cookie.secure) return true;
+  if (
+    cookie.name.startsWith("__Host-") &&
+    (!cookie.secure || cookie.domain.startsWith(".") || cookie.path !== "/")
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** True for hosts a browser treats as a secure context without TLS. */
+export function isLoopbackHost(hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  return (
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host === "[::1]" ||
+    /^127(?:\.\d{1,3}){3}$/.test(host)
+  );
+}
+
 /** RFC 6265 path match. */
 export function pathMatches(cookiePath: string, urlPath: string): boolean {
   if (urlPath === cookiePath) return true;
@@ -473,13 +521,17 @@ export function isExpired(cookie: Cookie): boolean {
   return cookie.expires < Date.now() / 1000;
 }
 
-/** Cookies that should be sent with a request to `url`. */
+/**
+ * Cookies that should be sent with a request to `url`: exact-host delivery for
+ * host-only cookies, domain delivery for dotted ones, then path and Secure.
+ * Secure cookies go over HTTPS and to loopback hosts, as in browsers.
+ */
 export function matchingCookies(store: CookieStore, url: string): Cookie[] {
   const parsed = new URL(url);
-  const isSecure = parsed.protocol === "https:";
+  const isSecure = parsed.protocol === "https:" || isLoopbackHost(parsed.hostname);
   return store.cookies.filter((c) => {
     if (isExpired(c)) return false;
-    if (!domainMatches(c.domain, parsed.hostname)) return false;
+    if (!cookieSendsToHost(c.domain, parsed.hostname)) return false;
     if (!pathMatches(c.path, parsed.pathname)) return false;
     if (c.secure && !isSecure) return false;
     return true;

package/src/lib/cookies/index.ts

@@ -4,12 +4,15 @@ export {
   type CookieJarOptions,
   type CookieStore,
   CookieStoreParseError,
+  cookieSendsToHost,
   domainMatches,
   type InfoResult,
   isExpired,
+  isLoopbackHost,
   matchingCookies,
   mergeCookies,
   type OriginEntry,
   pathMatches,
+  violatesCookiePrefix,
 } from "./client.js";
 export { applyExtraCookies, type ExtraCookies } from "./extra.js";

package/src/lib/docs-metadata-sync.ts

@@ -118,6 +118,33 @@ function addDays(value: string, days: number): string {
   return date.toISOString().replace(".000Z", "Z");
 }
 
+/** Allowance for clock skew between machines before a timestamp counts as future. */
+const FUTURE_SKEW_MS = 10 * 60 * 1000;
+
+/** Lifecycle timestamps record events that already happened, so none may be later than now. */
+const PAST_TIMESTAMP_FIELDS = [
+  "created_at",
+  "updated_at",
+  "status_changed_at",
+  "resolved_at",
+  "reviewed_at",
+] as const;
+
+function inFuture(value: unknown, now: string): boolean {
+  if (typeof value !== "string") return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && time > Date.parse(now) + FUTURE_SKEW_MS;
+}
+
+/**
+ * While a status is unchanged its status_changed_at is pinned to the committed
+ * value. A committed value later than now cannot be true, so a correction to a
+ * time that has already passed is accepted instead of being reverted.
+ */
+function correctsFutureStatusTime(committed: unknown, current: unknown, now: string): boolean {
+  return inFuture(committed, now) && typeof current === "string" && !inFuture(current, now);
+}
+
 export async function runDocsMetadataSync(
   opts: DocsMetadataSyncOpts,
 ): Promise<DocsMetadataSyncRow[]> {
@@ -171,7 +198,8 @@ export async function runDocsMetadataSync(
       if (
         !statusChanged &&
         beforeV2 &&
-        current.data.status_changed_at !== beforeV2.status_changed_at
+        current.data.status_changed_at !== beforeV2.status_changed_at &&
+        !correctsFutureStatusTime(beforeV2.status_changed_at, current.data.status_changed_at, now)
       ) {
         expected.status_changed_at = beforeV2.status_changed_at;
         fields.push("status_changed_at");
@@ -203,6 +231,19 @@ export async function runDocsMetadataSync(
         continue;
       }
       if (opts.check) {
+        const future = PAST_TIMESTAMP_FIELDS.filter((field) => inFuture(current.data[field], now));
+        if (future.length > 0) {
+          rows.push({
+            repo: target.name,
+            path,
+            status: "invalid",
+            fields: [...future],
+            message: future
+              .map((field) => `${field}: cannot be later than the current time`)
+              .join("; "),
+          });
+          continue;
+        }
         const validation = validateDocsMetadataV2(current.data);
         if (!validation.valid) {
           rows.push({
@@ -238,7 +279,8 @@ export async function runDocsMetadataSync(
         if (
           beforeV2 &&
           !statusChanged &&
-          current.data.status_changed_at !== beforeV2.status_changed_at
+          current.data.status_changed_at !== beforeV2.status_changed_at &&
+          !correctsFutureStatusTime(beforeV2.status_changed_at, current.data.status_changed_at, now)
         ) {
           drift.push("status_changed_at");
         }

package/src/lib/durable-job.ts

@@ -63,6 +63,11 @@ export interface DurableJobDocument {
   /** Directory the wrapped command runs in. */
   cwd: string;
   created_at: string;
+  /**
+   * Wait while Linux memory pressure is above this before queueing, as the
+   * foreground run does. The client resolves it from the resource's project config at launch.
+   */
+  defer_on_pressure?: { psi_full_avg10: number; max_wait_seconds: number };
 }
 
 export interface DurableJobStatus {
@@ -208,9 +213,19 @@ export function readJobDocument(jobDir: string): DurableJobDocument | null {
       : [],
     cwd: typeof parsed.cwd === "string" ? parsed.cwd : "",
     created_at: typeof parsed.created_at === "string" ? parsed.created_at : "",
+    ...readDeferOnPressure(parsed.defer_on_pressure),
   };
 }
 
+function readDeferOnPressure(value: unknown): Pick<DurableJobDocument, "defer_on_pressure"> {
+  if (!isRecord(value)) return {};
+  const threshold = value.psi_full_avg10;
+  const maxWait = value.max_wait_seconds;
+  return typeof threshold === "number" && typeof maxWait === "number" && maxWait > 0
+    ? { defer_on_pressure: { psi_full_avg10: threshold, max_wait_seconds: maxWait } }
+    : {};
+}
+
 /** 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);

package/src/lib/http/client.ts

@@ -2,7 +2,9 @@ import {
   applyExtraCookies,
   type Cookie,
   type CookieJar,
+  domainMatches,
   type ExtraCookies,
+  violatesCookiePrefix,
 } from "../cookies/index.ts";
 
 /**
@@ -52,6 +54,15 @@ export interface FetchOptions<TResponseType extends FetchResponseType = "text">
   extraCookies?: ExtraCookies;
   /** Response body representation. Default `text`; use `bytes` for lossless file output. */
   responseType?: TResponseType;
+  /**
+   * With `redirect: "follow"`, follow redirects in this client instead of the
+   * runtime's fetch. Every hop then gets its own cookie header, `extraHeaders`
+   * call, and Set-Cookie persistence, so a caller that inspects those can stop
+   * a chain between hops. Credential headers are dropped on a cross-origin hop.
+   * Default: on whenever a `jar` is passed (host-only cookies must follow the
+   * jar's exact-host rule on every hop), off without one.
+   */
+  clientRedirects?: boolean;
 }
 
 type FetchBody<TResponseType extends FetchResponseType> = TResponseType extends "bytes"
@@ -76,9 +87,55 @@ export interface FetchResult<TBody = string> {
  * Streams aren't supported; this is a CLI helper, not a streaming HTTP
  * client. Use Bun's `fetch` directly for streaming workloads.
  */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_CLIENT_REDIRECTS = 20;
+
 export async function fetchWithJar<TResponseType extends FetchResponseType = "text">(
   url: string,
   opts: FetchOptions<TResponseType> = {},
+): Promise<FetchResult<FetchBody<TResponseType>>> {
+  // With a jar, redirects are followed here so every hop gets its own Cookie
+  // header from the jar (exact-host for host-only cookies) and its own
+  // Set-Cookie persistence; the runtime would otherwise carry or drop the
+  // first hop's header on its own rules. Pass `clientRedirects: false` to opt out.
+  const clientRedirects = opts.clientRedirects ?? Boolean(opts.jar);
+  if (!clientRedirects || (opts.redirect ?? "follow") !== "follow") return fetchOnce(url, opts);
+
+  let current = url;
+  let method = opts.method ?? "GET";
+  let body = opts.body;
+  let headers = opts.headers;
+  let cookiesSaved = 0;
+  for (let hop = 0; ; hop++) {
+    const result = await fetchOnce(current, { ...opts, method, body, headers, redirect: "manual" });
+    cookiesSaved += result.cookiesSaved;
+    const location = result.headers.location;
+    if (!REDIRECT_STATUSES.has(result.status) || !location) return { ...result, cookiesSaved };
+    if (hop >= MAX_CLIENT_REDIRECTS) {
+      throw new Error(`Too many redirects (more than ${MAX_CLIENT_REDIRECTS}) starting at ${url}`);
+    }
+    const next = new URL(location, current);
+    if (
+      result.status === 303 ||
+      ((result.status === 301 || result.status === 302) && method !== "GET" && method !== "HEAD")
+    ) {
+      method = "GET";
+      body = undefined;
+    }
+    if (next.origin !== new URL(current).origin && headers) {
+      headers = Object.fromEntries(
+        Object.entries(headers).filter(
+          ([name]) => !["authorization", "cookie"].includes(name.toLowerCase()),
+        ),
+      );
+    }
+    current = next.href;
+  }
+}
+
+async function fetchOnce<TResponseType extends FetchResponseType = "text">(
+  url: string,
+  opts: FetchOptions<TResponseType> = {},
 ): Promise<FetchResult<FetchBody<TResponseType>>> {
   const headers: Record<string, string> = { ...(opts.headers ?? {}) };
 
@@ -229,7 +286,9 @@ function parseSetCookie(raw: string, defaultDomain: string): Cookie | null {
   for (const attr of parts.slice(1)) {
     const lower = attr.toLowerCase();
     if (lower.startsWith("domain=")) {
-      const d = attr.slice(7).trim();
+      const d = attr.slice(7).trim().toLowerCase();
+      // A server may only scope a cookie to its own host or a parent domain.
+      if (!d || !domainMatches(d, defaultDomain)) return null;
       cookie.domain = d.startsWith(".") ? d : `.${d}`;
     } else if (lower.startsWith("path=")) {
       cookie.path = attr.slice(5).trim() || "/";
@@ -255,5 +314,8 @@ function parseSetCookie(raw: string, defaultDomain: string): Cookie | null {
     }
   }
 
+  // A cookie that breaks its name prefix is dropped, as a browser would.
+  if (violatesCookiePrefix(cookie)) return null;
+
   return cookie;
 }

package/src/lib/instructions/templates.ts

@@ -133,10 +133,10 @@ 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.
+agent by name, running or not, here or on another machine sharing this origin:
+a live agent sees it on their next prompt (after a fetch, if remote), and a
+dormant name holds it until that session next starts. Send it as your only step;
+do not check who is live first or hunt elsewhere. Only an unused name is refused.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;

package/dist/core/agents/state/process-handle.d.ts

@@ -1,26 +0,0 @@
-import type { ProcessGenerationVerdict } from "./proc-start.js";
-export interface ProcessHandleSignalResult {
-    sent: boolean;
-    verdict: ProcessGenerationVerdict;
-}
-export type NativeProcessHelperRunner = (command: string, args: string[], options: {
-    input: string;
-    encoding: "utf8";
-    timeout: number;
-    maxBuffer: number;
-    windowsHide: boolean;
-}) => {
-    status: number | null;
-    stdout: string | Buffer | null;
-    error?: Error;
-};
-export declare const LINUX_PROCESS_HANDLE_SCRIPT = "\nimport json, os, pathlib, signal, sys\nresult = {\"sent\": False, \"verdict\": \"unknown\"}\nfd = None\ntry:\n    request = json.loads(sys.stdin.readline())\n    if not hasattr(os, \"pidfd_open\") or not hasattr(signal, \"pidfd_send_signal\"):\n        raise RuntimeError(\"pidfd support unavailable\")\n    fd = os.pidfd_open(request[\"pid\"])\n    stat = pathlib.Path(\"/proc/%d/stat\" % request[\"pid\"]).read_text()\n    ticks = stat[stat.rfind(\") \") + 2:].split()[19]\n    boot = pathlib.Path(\"/proc/sys/kernel/random/boot_id\").read_text().strip().replace(\"-\", \"\")[:8]\n    token = \"l%s.%s\" % (boot, ticks)\n    result[\"token\"] = token\n    recorded = request.get(\"token\")\n    result[\"verdict\"] = \"same\" if token == recorded else \"different\"\n    if request[\"mode\"] == \"signal\" and result[\"verdict\"] == \"same\":\n        print(json.dumps({\"phase\": \"verified\"}), flush=True)\n        if sys.stdin.readline().strip() == \"signal\":\n            signal.pidfd_send_signal(fd, request[\"signal\"])\n            result[\"sent\"] = True\nexcept Exception:\n    pass\nfinally:\n    if fd is not None:\n        os.close(fd)\nprint(json.dumps(result), flush=True)\n";
-export declare const WINDOWS_PROCESS_HANDLE_SCRIPT = "\n$ErrorActionPreference = 'Stop'\n$result = @{ sent = $false; verdict = 'unknown' }\n$handle = [IntPtr]::Zero\ntry {\n  Add-Type -TypeDefinition @'\nusing System;\nusing System.Runtime.InteropServices;\npublic static class HarneryProcessHandle {\n  [DllImport(\"kernel32.dll\", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, uint processId);\n  [DllImport(\"kernel32.dll\", SetLastError=true)] public static extern bool GetProcessTimes(IntPtr handle, out long creation, out long exit, out long kernel, out long user);\n  [DllImport(\"kernel32.dll\", SetLastError=true)] public static extern bool TerminateProcess(IntPtr handle, uint exitCode);\n  [DllImport(\"kernel32.dll\")] public static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);\n  [DllImport(\"kernel32.dll\")] public static extern bool CloseHandle(IntPtr handle);\n}\n'@\n  $request = [Console]::In.ReadLine() | ConvertFrom-Json\n  $access = [uint32]0x101000\n  if ($request.mode -eq 'signal') { $access = $access -bor 1 }\n  $handle = [HarneryProcessHandle]::OpenProcess($access, $false, [uint32]$request.pid)\n  if ($handle -eq [IntPtr]::Zero) { throw 'process handle unavailable' }\n  [long]$creation = 0; [long]$exitTime = 0; [long]$kernel = 0; [long]$userTime = 0\n  if (-not [HarneryProcessHandle]::GetProcessTimes($handle, [ref]$creation, [ref]$exitTime, [ref]$kernel, [ref]$userTime)) { throw 'process time unavailable' }\n  $token = 'w' + $creation.ToString([Globalization.CultureInfo]::InvariantCulture)\n  $result.token = $token\n  $result.verdict = if ($token -ceq $request.token) { 'same' } else { 'different' }\n  if ($request.mode -eq 'signal' -and $result.verdict -eq 'same') {\n    [Console]::Out.WriteLine('{\"phase\":\"verified\"}')\n    [Console]::Out.Flush()\n    if ([Console]::In.ReadLine() -eq 'signal' -and [HarneryProcessHandle]::WaitForSingleObject($handle, 0) -eq 258) {\n      $result.sent = [HarneryProcessHandle]::TerminateProcess($handle, 1)\n    }\n  }\n} catch {} finally {\n  if ($handle -ne [IntPtr]::Zero) { [void][HarneryProcessHandle]::CloseHandle($handle) }\n}\n$result | ConvertTo-Json -Compress\n";
-/** Windows creation FILETIME, read from an OpenProcess handle. */
-export declare function windowsProcessStartToken(pid: number, run?: NativeProcessHelperRunner): string | null;
-/** No numeric-PID signaling fallback is permitted when an exact handle fails. */
-export declare function signalProcessWithHandle(pid: number, recordedToken: string, signal: NodeJS.Signals | number, options?: {
-    platform?: NodeJS.Platform;
-    run?: NativeProcessHelperRunner;
-}): ProcessHandleSignalResult;
-//# sourceMappingURL=process-handle.d.ts.map

package/dist/core/agents/state/process-handle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"process-handle.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/process-handle.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAMD,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,KACE;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAI9E,eAAO,MAAM,2BAA2B,+qCA2BvC,CAAC;AAEF,eAAO,MAAM,6BAA6B,qnEAqCzC,CAAC;AAwCF,kEAAkE;AAClE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,yBAAqC,GACzC,MAAM,GAAG,IAAI,CAGf;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAC/B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAAC,GAAG,CAAC,EAAE,yBAAyB,CAAA;CAAO,GAC5E,yBAAyB,CAgB3B"}