@scp-dev/core 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -346,7 +346,7 @@ declare const LIMITS: {
     readonly hookEndedGraceS: 30;
     readonly restartGraceS: 60;
     readonly injectMessages: 5;
-    readonly injectBytes: 4096;
+    readonly injectBytes: 7168;
     readonly pushBytes: 20480;
     /** the stops a session's push may continue between two prompts */
     readonly pushes: 20;
@@ -422,6 +422,12 @@ declare const MESSAGE_KINDS: readonly MessageKind[];
 declare const STATUS_STATES: readonly StatusState[];
 declare function validHandle(handle: string): boolean;
 declare function validHarness(harness: string): boolean;
+/** harness names of the path a claim came by (a bare CLI, hook or MCP shim), not of the agent behind it */
+declare const GENERIC_HARNESSES: ReadonlySet<string>;
+/** whether a claim of harness `claimed` may take a row of harness `held`: the same harness, or a generic row, which heals to the claim's */
+declare function harnessFits(held: string | null, claimed: string): boolean;
+/** the harness a claimed row keeps: the claim's, except that a generic claim never replaces a known harness */
+declare function keptHarness(held: string | null, claimed: string): string;
 interface Claim {
     handle?: string;
     harness?: string;
@@ -1103,6 +1109,10 @@ interface EndpointRow {
     linked: number | null;
     /** how the session that holds the endpoint wakes it: a {@link Wake} other than none, or null */
     wake: string | null;
+    /** the live connections that set the wake */
+    wakers: number;
+    /** when the last hook connection that set the wake closed */
+    waker_left: number | null;
 }
 interface MessageRow {
     id: string;
@@ -1165,6 +1175,8 @@ declare class RelayCore {
     constructor(sql: Sql, options: CoreOptions);
     /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
     private machineLabel;
+    /** this host's own agent rows labelled with another machine (its name before a rename, or its hostname) take its machine name */
+    relabelMachine(): number;
     migrate(): void;
     /** every stored list that is exactly `tree:self`, the tree preset's old list, narrows once to the preset's list */
     private migrateTreePreset;
@@ -1250,6 +1262,8 @@ declare class RelayCore {
      * whether a claim placed under `parent` restarts `row`: it lands where `row` sits (under `row`'s parent, or a root with no placement), or on
      * `row` itself from `row`'s own process; never under `row` or elsewhere in its tree
      */
+    /** a local row held only by connections whose harness process exited, as a shim that outlived its harness leaves it */
+    private outlived;
     private restarts;
     /**
      * whether the claim re-claims `row` with the grant `row` spent: from `row`'s own process or one of its ancestors, or with no lineage from
@@ -1338,6 +1352,13 @@ declare class RelayCore {
         transient?: boolean;
         process?: string;
     }): boolean;
+    /**
+     * a connection that set the endpoint's wake starts (`live`) or stops counting as its waker. A hook's (`grace`) still counts for
+     * LIMITS.restartGraceS after it closes, while its harness starts the next one
+     */
+    waker(endpoint: string, live: boolean, options?: {
+        grace?: boolean;
+    }): void;
     /**
      * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
      * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
@@ -2492,4 +2513,4 @@ declare function sha256Hex(text: string): string;
 /** the UTF-8 byte length of text, the unit every byte limit counts in */
 declare function utf8Bytes(text: string): number;
 
-export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, WAKES, type Wake, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presenceText, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, wakeText, widenText, wrapMessage, wrapPeek, xlimits };
+export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GENERIC_HARNESSES, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, WAKES, type Wake, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, harnessFits, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, keptHarness, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presenceText, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, wakeText, widenText, wrapMessage, wrapPeek, xlimits };

package/dist/index.js

@@ -126,7 +126,7 @@ var LIMITS = {
   hookEndedGraceS: 30,
   restartGraceS: 60,
   injectMessages: 5,
-  injectBytes: 4096,
+  injectBytes: 7168,
   pushBytes: 20480,
   /** the stops a session's push may continue between two prompts */
   pushes: 20,
@@ -192,6 +192,14 @@ function validHandle(handle) {
 function validHarness(harness) {
   return HARNESS.test(harness);
 }
+var GENERIC_HARNESSES = /* @__PURE__ */ new Set(["cli", "hook", "mcp", "shell"]);
+var generic = (harness) => harness === null || GENERIC_HARNESSES.has(harness);
+function harnessFits(held, claimed) {
+  return held === claimed || generic(held);
+}
+function keptHarness(held, claimed) {
+  return generic(claimed) && !generic(held) ? held : claimed;
+}
 var SCOPE_PRESETS = ["open", "tree", "parent", "none"];
 var SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"];
 
@@ -1086,6 +1094,7 @@ function utf8Bytes(text) {
 }
 
 // src/core.ts
+var GENERIC_SQL = `harness IN (${[...GENERIC_HARNESSES].map((h) => `'${h}'`).join(", ")})`;
 var HUMAN_HANDLE = "_human";
 var TITLE_CHARS = 64;
 var SYSTEM_HANDLE = "_relay";
@@ -1297,6 +1306,19 @@ var RelayCore = class {
     if (this.namedMachine !== null && labels.machine !== void 0 && labels.machine === this.hostname) labels.machine = this.namedMachine;
     return labels;
   }
+  /** this host's own agent rows labelled with another machine (its name before a rename, or its hostname) take its machine name */
+  relabelMachine() {
+    const machine = this.namedMachine;
+    if (machine === null) return 0;
+    let changed = 0;
+    for (const row of this.sql.all(`SELECT * FROM endpoints WHERE kind = 'agent' AND labels LIKE '%"machine"%'`)) {
+      const labels = json(row.labels, {});
+      if (labels.machine === void 0 || labels.machine === machine || !this.localRow(row)) continue;
+      this.sql.all(`UPDATE endpoints SET labels = ? WHERE id = ?`, JSON.stringify({ ...labels, machine }), row.id);
+      changed++;
+    }
+    return changed;
+  }
   migrate() {
     for (const statement of MIGRATION) this.sql.all(statement);
     const columns = this.sql.all(`PRAGMA table_info(idempotency)`).map((c) => c.name);
@@ -1335,7 +1357,9 @@ var RelayCore = class {
       ["tldr_turn", "INTEGER"],
       ["named", "INTEGER"],
       ["linked", "INTEGER"],
-      ["wake", "TEXT"]
+      ["wake", "TEXT"],
+      ["wakers", "INTEGER NOT NULL DEFAULT 0"],
+      ["waker_left", "INTEGER"]
     ]) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`);
     }
@@ -1595,7 +1619,7 @@ var RelayCore = class {
     const bare = transient && fields.session !== null && BARE_PID_KEY.test(fields.session);
     let row = fields.session ? one(
       this.sql,
-      `SELECT * FROM endpoints WHERE kind = 'agent' AND harness = ?
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND (harness = ? OR ${GENERIC_SQL})
            AND (session = ? OR (? = 1 AND substr(session, 1, ?) = ? AND (connections = 0 OR hook_seen >= ?)))
            AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}' ORDER BY COALESCE(last_seen, created_at) DESC LIMIT 1`,
       harness,
@@ -1612,7 +1636,7 @@ var RelayCore = class {
     if (row && presenceOf(row, now) === "offline") {
       this.sql.all(`UPDATE endpoints SET session = NULL WHERE id = ?`, row.id);
       row = void 0;
-    } else if (row && !transient && !sameProcess(row, fields.process)) {
+    } else if (row && !transient && !sameProcess(row, fields.process) && !(row.handle === wanted && reclaims(row, fields.process))) {
       row = void 0;
       session = null;
     } else if (row && !transient && row.token_hash === null && row.named === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
@@ -1624,7 +1648,7 @@ var RelayCore = class {
         if (!held) {
           this.sql.all(`UPDATE endpoints SET handle = ? WHERE id = ?`, handle, hooks.id);
           settled = true;
-        } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && held.harness === harness) {
+        } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && harnessFits(held.harness, harness)) {
           if (this.restarts(held, this.placement(scope, now).parent, fields.process) || this.redeems(held, scope, { harness, ...fields })) {
             ;
             ({ moved, stopBlocks } = this.leaveHooks(hooks, held.id));
@@ -1654,12 +1678,12 @@ var RelayCore = class {
         this.sql.all(`INSERT INTO endpoints (id, handle, kind, harness, labels, created_at) VALUES (?, ?, 'agent', ?, '{}', ?)`, id, handle, harness, now);
         row = this.byId(id);
         created = true;
-      } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && held.harness === harness && held.id !== scope.subagent?.root && !(scope.subagent && held.session?.startsWith("sub:") && held.session !== fields.session)) {
+      } else if (held.kind === "agent" && (held.connections === 0 && presenceOf(held, now) === "offline" || !transient && this.outlived(held)) && harnessFits(held.harness, harness) && held.id !== scope.subagent?.root && !(scope.subagent && held.session?.startsWith("sub:") && held.session !== fields.session)) {
         own = transient && held.process !== null && fields.process !== null && sameHarness(held.process, fields.process);
         const ended = held.hook_ended !== null || (held.last_seen ?? held.created_at) < now - LIMITS.restartGraceS * 1e3;
         if ((!transient || own || ended) && (this.restarts(held, this.placement(scope, now).parent, fields.process) || this.redeems(held, scope, { harness, ...fields })))
           row = held;
-      } else if (scope.exact && held.kind === "agent" && held.process === null && held.session === null && held.harness === harness && this.restarts(held, this.placement(scope, now).parent, null)) {
+      } else if (scope.exact && held.kind === "agent" && held.process === null && held.session === null && harnessFits(held.harness, harness) && this.restarts(held, this.placement(scope, now).parent, null)) {
         row = held;
         joined = true;
         live = presenceOf(held, now) !== "offline";
@@ -1684,7 +1708,7 @@ var RelayCore = class {
        stop_blocks = CASE WHEN ? IS NOT NULL THEN ? WHEN ? IS NOT NULL AND session IS NOT ? THEN 0 ELSE stop_blocks END,
        briefed = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE introduced END,
        directive_holds = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE directive_holds END WHERE id = ?`,
-      harness,
+      keptHarness(row.harness, harness),
       fields.model,
       fields.cwd,
       fields.parent,
@@ -1813,7 +1837,7 @@ var RelayCore = class {
     if ((held.session !== null || held.process !== null) && presenceOf(held, now) !== "offline") {
       return new RelayError("unauthorized", `${handle} is held by a live ${held.harness} session: act as it from that session's own shell, no --as needed`);
     }
-    if (held.harness !== harness) return new RelayError("unauthorized", `${handle} is a ${held.harness} endpoint: pass --harness ${held.harness}`);
+    if (!harnessFits(held.harness, harness)) return new RelayError("unauthorized", `${handle} is a ${held.harness} endpoint: pass --harness ${held.harness}`);
     return new RelayError("unauthorized", `${handle} is placed in another tree or under another parent than this shell`);
   }
   /**
@@ -1863,6 +1887,11 @@ var RelayCore = class {
    * whether a claim placed under `parent` restarts `row`: it lands where `row` sits (under `row`'s parent, or a root with no placement), or on
    * `row` itself from `row`'s own process; never under `row` or elsewhere in its tree
    */
+  /** a local row held only by connections whose harness process exited, as a shim that outlived its harness leaves it */
+  outlived(row) {
+    const pid = Number(/^pid:(\d+):/.exec(row.process ?? "")?.[1]);
+    return row.connections > 0 && pid > 0 && this.localRow(row) && !this.alive(pid);
+  }
   restarts(row, parent, process) {
     if (parent?.id === row.id) return process !== null && row.process !== null && sameHarness(row.process, process);
     return (parent?.id ?? null) === row.parent_ep || parent === null && row.linked !== null;
@@ -1875,7 +1904,7 @@ var RelayCore = class {
     const spent = this.spentGrant(scope);
     if (spent?.used_by !== row.id) return false;
     const lineage = this.lineageParent(scope.lineage);
-    if (!lineage) return row.harness === claimant.harness && spent.spent_cwd !== null && spent.spent_cwd === claimant.cwd;
+    if (!lineage) return harnessFits(row.harness, claimant.harness) && spent.spent_cwd !== null && spent.spent_cwd === claimant.cwd;
     return this.restarts(row, lineage, claimant.process) || this.ancestorsOf(row).includes(lineage.id);
   }
   /** the claim's grant, when an endpoint spent it */
@@ -2027,7 +2056,7 @@ var RelayCore = class {
       endpoint
     );
     const row = this.mustEndpoint(endpoint);
-    if (!options.settle || presenceOf(row, now) !== "offline" || row.status_state !== "working" && row.status_state !== "waiting") return false;
+    if (!options.settle || shownPresence(row, now) !== "offline" || row.status_state !== "working" && row.status_state !== "waiting") return false;
     this.sql.all(`UPDATE endpoints SET status_state = NULL, status_note = NULL WHERE id = ?`, endpoint);
     return true;
   }
@@ -2042,6 +2071,7 @@ var RelayCore = class {
       `UPDATE endpoints SET connections = 0, hook_seen = CASE WHEN kind = 'agent' AND hook_ended IS NULL THEN MAX(COALESCE(hook_seen, 0), ?) ELSE hook_seen END WHERE connections > 0`,
       this.now() - (LIMITS.hookIdleS - LIMITS.restartGraceS) * 1e3
     );
+    this.sql.all(`UPDATE endpoints SET wakers = 0, waker_left = ? WHERE wakers > 0`, this.now());
   }
   whoami(endpoint) {
     return this.view(this.mustEndpoint(endpoint));
@@ -2059,7 +2089,7 @@ var RelayCore = class {
     const viewer = filters.viewer === void 0 ? void 0 : this.mustEndpoint(filters.viewer);
     const shown = viewer ? new Set(this.visibleRows(viewer).map((row) => row.id)) : void 0;
     const peeker = viewer ?? (filters.peekable === true ? this.byHandle(HUMAN_HANDLE) : void 0);
-    return this.listed().filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff).filter((row) => !filters.harness || row.harness === filters.harness).filter((row) => !filters.kind || row.kind === filters.kind).filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human")).map((row) => {
+    return this.listed().filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now)).filter((row) => !filters.harness || row.harness === filters.harness).filter((row) => !filters.kind || row.kind === filters.kind).filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human")).map((row) => {
       const view = this.view(row, shown);
       return peeker && this.peekableBy(peeker, row, viewer?.kind === "human") ? { ...view, peekable: row.peek } : view;
     }).filter((view) => !filters.presence || view.presence === filters.presence);
@@ -2159,6 +2189,20 @@ var RelayCore = class {
     this.sql.all(`UPDATE endpoints SET wake = ? WHERE id = ?`, wake, endpoint);
     return true;
   }
+  /**
+   * a connection that set the endpoint's wake starts (`live`) or stops counting as its waker. A hook's (`grace`) still counts for
+   * LIMITS.restartGraceS after it closes, while its harness starts the next one
+   */
+  waker(endpoint, live, options = {}) {
+    if (live) this.sql.all(`UPDATE endpoints SET wakers = wakers + 1 WHERE id = ?`, endpoint);
+    else
+      this.sql.all(
+        `UPDATE endpoints SET wakers = MAX(wakers - 1, 0), waker_left = CASE WHEN ? THEN ? ELSE waker_left END WHERE id = ?`,
+        options.grace ? 1 : 0,
+        this.now(),
+        endpoint
+      );
+  }
   /**
    * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
    * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
@@ -2460,7 +2504,7 @@ var RelayCore = class {
     const recipients = [...new Map(resolved.map((row) => [row.id, row])).values()];
     if (params.live !== void 0 && typeof params.live !== "boolean") throw new RelayError("invalid_params", "live must be true or false");
     const dark = recipients.filter(
-      (r) => r.kind === "agent" && presenceOf(r, now) === "offline" && (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || r.session === null && r.token_hash === null && r.hook_ended !== null) && !this.unjoinedSpawn(sender, r.handle, now)
+      (r) => r.kind === "agent" && shownPresence(r, now) === "offline" && (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || r.session === null && r.token_hash === null && r.hook_ended !== null) && !this.unjoinedSpawn(sender, r.handle, now)
     );
     if (params.live === true && dark.length)
       throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`);
@@ -2705,7 +2749,7 @@ var RelayCore = class {
   reach(sender, recipient, offline, now) {
     if (recipient.kind !== "agent" || !this.localRow(recipient)) return void 0;
     const done = recipient.status_state === "done";
-    if ((done || presenceOf(recipient, now) === "offline") && this.unjoinedSpawn(sender, recipient.handle, now)) return "starting";
+    if ((done || shownPresence(recipient, now) === "offline") && this.unjoinedSpawn(sender, recipient.handle, now)) return "starting";
     if (done) return "ended";
     return offline ? "offline" : "running";
   }
@@ -3104,7 +3148,7 @@ var RelayCore = class {
         continue;
       }
       const row = this.byId(grant.used_by);
-      if (!row || row.status_state === "done" || presenceOf(row, now) === "offline" && (grant.handback !== null || !pid || !this.alive(pid))) continue;
+      if (!row || row.status_state === "done" || shownPresence(row, now) === "offline" && (grant.handback !== null || !pid || !this.alive(pid))) continue;
       workers.set(row.id, row);
       if (grant.pushed_at !== null && grant.pushed_at > now - LIMITS.pushGapS * 1e3) paced.add(row.id);
     }
@@ -3467,9 +3511,9 @@ var RelayCore = class {
       request,
       endpoint
     ).filter(
-      (row) => present ? present.includes(row.id) : presenceOf(row, now) !== "offline" || Math.max(row.last_seen ?? 0, row.hook_seen ?? 0, row.hook_ended ?? 0) >= asked.created_at
+      (row) => present ? present.includes(row.id) : shownPresence(row, now) !== "offline" || Math.max(row.last_seen ?? 0, row.hook_seen ?? 0, row.hook_ended ?? 0) >= asked.created_at
     );
-    const gone = (row) => presenceOf(row, now) === "offline" && ((row.hook_ended ?? 0) >= asked.created_at || row.status_state === "done" || now - Math.max(row.last_seen ?? 0, row.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS);
+    const gone = (row) => shownPresence(row, now) === "offline" && ((row.hook_ended ?? 0) >= asked.created_at || row.status_state === "done" || now - Math.max(row.last_seen ?? 0, row.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS);
     if (!rows.length || !rows.every(gone)) return null;
     return rows.map((row) => ({ address: this.address(row), state: row.status_state }));
   }
@@ -3564,7 +3608,7 @@ var RelayCore = class {
     for (const row of this.sql.all(
       `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND status_state IN ('working', 'waiting')`
     )) {
-      if (this.localRow(row) && presenceOf(row, now) === "offline")
+      if (this.localRow(row) && shownPresence(row, now) === "offline")
         this.sql.all(`UPDATE endpoints SET status_state = NULL, status_note = NULL WHERE id = ?`, row.id);
     }
   }
@@ -5373,7 +5417,7 @@ ${stderr}` : "";
   }
   /** with `shown`, the ids a viewer sees: a parent outside it is null */
   view(row, shown) {
-    const presence = presenceOf(row, this.now());
+    const presence = shownPresence(row, this.now());
     return {
       id: row.id,
       address: this.address(row),
@@ -5566,6 +5610,9 @@ function unreachable(address) {
 var PROCESS_KEY = /^pid:\d+:[A-Za-z0-9:-]{1,64}$/;
 var BARE_PID_KEY = /^pid:\d+$/;
 var ANY_PROCESS_KEY = /^pid:\d+(:[A-Za-z0-9:-]{1,64})?$/;
+function reclaims(row, key) {
+  return row.connections > 0 && key !== null && row.process === key && PROCESS_KEY.test(key);
+}
 function sameProcess(row, key) {
   if (row.connections > 0 || key === null || row.process === null) return false;
   return row.token_hash === null ? sameHarness(row.process, key) : row.process === key && PROCESS_KEY.test(key);
@@ -5606,6 +5653,13 @@ function presenceOf(row, now) {
   if (row.hook_seen >= now - LIMITS.hookOnlineS * 1e3) return "online";
   return row.hook_seen >= now - LIMITS.hookIdleS * 1e3 ? "idle" : "offline";
 }
+function waking(row, now) {
+  return wakeOf(row) !== null && (row.wakers > 0 || (row.waker_left ?? 0) >= now - LIMITS.restartGraceS * 1e3);
+}
+function shownPresence(row, now) {
+  const presence = presenceOf(row, now);
+  return presence === "offline" && waking(row, now) ? "idle" : presence;
+}
 function pairKey(a, b) {
   return a < b ? `${a}|${b}` : `${b}|${a}`;
 }
@@ -6387,6 +6441,7 @@ export {
   DEFAULT_JUDGE_EFFORT,
   ERROR_CODES,
   FakeJudgeClient,
+  GENERIC_HARNESSES,
   GONE_PREFIX,
   GROUP_NAME,
   HANDBACK_CUT,
@@ -6449,6 +6504,7 @@ export {
   gateRefusal,
   groupCapKey,
   handbackOutput,
+  harnessFits,
   hasScope,
   honestSender,
   isLeaving,
@@ -6459,6 +6515,7 @@ export {
   judgeModel,
   judgePrompt,
   keepLast,
+  keptHarness,
   leavesFleet,
   matches,
   mergeVerdicts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/core",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Swarm Communication Protocol core: wire types, framing, scopes, policy, judge and the relay core.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",

package/src/core.ts

@@ -38,6 +38,9 @@ import {
   type StopNudge,
   type StopWaitResult,
   type ThreadMessage,
+  GENERIC_HARNESSES,
+  harnessFits,
+  keptHarness,
   validHandle,
   validHarness,
   type Wake,
@@ -70,6 +73,8 @@ import { findSecret, redactSecrets } from "./scrub"
 import { one, type Sql, type SqlValue } from "./sql"
 import { utf8Bytes } from "./utf8"
 
+const GENERIC_SQL = `harness IN (${[...GENERIC_HARNESSES].map((h) => `'${h}'`).join(", ")})`
+
 export const HUMAN_HANDLE = "_human"
 /** an agent title's length cap */
 export const TITLE_CHARS = 64
@@ -262,6 +267,10 @@ export interface EndpointRow {
   linked: number | null
   /** how the session that holds the endpoint wakes it: a {@link Wake} other than none, or null */
   wake: string | null
+  /** the live connections that set the wake */
+  wakers: number
+  /** when the last hook connection that set the wake closed */
+  waker_left: number | null
 }
 
 export interface MessageRow {
@@ -491,6 +500,20 @@ export class RelayCore {
     return labels
   }
 
+  /** this host's own agent rows labelled with another machine (its name before a rename, or its hostname) take its machine name */
+  relabelMachine(): number {
+    const machine = this.namedMachine
+    if (machine === null) return 0
+    let changed = 0
+    for (const row of this.sql.all<EndpointRow>(`SELECT * FROM endpoints WHERE kind = 'agent' AND labels LIKE '%"machine"%'`)) {
+      const labels = json<Record<string, string>>(row.labels, {})
+      if (labels.machine === undefined || labels.machine === machine || !this.localRow(row)) continue
+      this.sql.all(`UPDATE endpoints SET labels = ? WHERE id = ?`, JSON.stringify({ ...labels, machine }), row.id)
+      changed++
+    }
+    return changed
+  }
+
   migrate(): void {
     for (const statement of MIGRATION) this.sql.all(statement)
     const columns = this.sql.all<{ name: string }>(`PRAGMA table_info(idempotency)`).map((c) => c.name)
@@ -530,6 +553,8 @@ export class RelayCore {
       ["named", "INTEGER"],
       ["linked", "INTEGER"],
       ["wake", "TEXT"],
+      ["wakers", "INTEGER NOT NULL DEFAULT 0"],
+      ["waker_left", "INTEGER"],
     ] as const) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`)
     }
@@ -811,7 +836,7 @@ export class RelayCore {
     let row = fields.session
       ? one<EndpointRow>(
           this.sql,
-          `SELECT * FROM endpoints WHERE kind = 'agent' AND harness = ?
+          `SELECT * FROM endpoints WHERE kind = 'agent' AND (harness = ? OR ${GENERIC_SQL})
            AND (session = ? OR (? = 1 AND substr(session, 1, ?) = ? AND (connections = 0 OR hook_seen >= ?)))
            AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}' ORDER BY COALESCE(last_seen, created_at) DESC LIMIT 1`,
           harness,
@@ -829,7 +854,7 @@ export class RelayCore {
     if (row && presenceOf(row, now) === "offline") {
       this.sql.all(`UPDATE endpoints SET session = NULL WHERE id = ?`, row.id)
       row = undefined
-    } else if (row && !transient && !sameProcess(row, fields.process)) {
+    } else if (row && !transient && !sameProcess(row, fields.process) && !(row.handle === wanted && reclaims(row, fields.process))) {
       row = undefined
       session = null
     } else if (
@@ -848,7 +873,7 @@ export class RelayCore {
         if (!held) {
           this.sql.all(`UPDATE endpoints SET handle = ? WHERE id = ?`, handle, hooks.id)
           settled = true
-        } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && held.harness === harness) {
+        } else if (held.kind === "agent" && held.connections === 0 && presenceOf(held, now) === "offline" && harnessFits(held.harness, harness)) {
           if (this.restarts(held, this.placement(scope, now).parent, fields.process) || this.redeems(held, scope, { harness, ...fields })) {
             ;({ moved, stopBlocks } = this.leaveHooks(hooks, held.id))
             row = undefined
@@ -879,9 +904,8 @@ export class RelayCore {
         created = true
       } else if (
         held.kind === "agent" &&
-        held.connections === 0 &&
-        presenceOf(held, now) === "offline" &&
-        held.harness === harness &&
+        ((held.connections === 0 && presenceOf(held, now) === "offline") || (!transient && this.outlived(held))) &&
+        harnessFits(held.harness, harness) &&
         held.id !== scope.subagent?.root &&
         !(scope.subagent && held.session?.startsWith("sub:") && held.session !== fields.session)
       ) {
@@ -897,7 +921,7 @@ export class RelayCore {
         held.kind === "agent" &&
         held.process === null &&
         held.session === null &&
-        held.harness === harness &&
+        harnessFits(held.harness, harness) &&
         this.restarts(held, this.placement(scope, now).parent, null)
       ) {
         row = held
@@ -924,7 +948,7 @@ export class RelayCore {
        stop_blocks = CASE WHEN ? IS NOT NULL THEN ? WHEN ? IS NOT NULL AND session IS NOT ? THEN 0 ELSE stop_blocks END,
        briefed = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE introduced END,
        directive_holds = CASE WHEN ? IS NOT NULL AND session IS NOT ? THEN NULL ELSE directive_holds END WHERE id = ?`,
-      harness,
+      keptHarness(row.harness, harness),
       fields.model,
       fields.cwd,
       fields.parent,
@@ -1062,7 +1086,7 @@ export class RelayCore {
     if ((held.session !== null || held.process !== null) && presenceOf(held, now) !== "offline") {
       return new RelayError("unauthorized", `${handle} is held by a live ${held.harness} session: act as it from that session's own shell, no --as needed`)
     }
-    if (held.harness !== harness) return new RelayError("unauthorized", `${handle} is a ${held.harness} endpoint: pass --harness ${held.harness}`)
+    if (!harnessFits(held.harness, harness)) return new RelayError("unauthorized", `${handle} is a ${held.harness} endpoint: pass --harness ${held.harness}`)
     return new RelayError("unauthorized", `${handle} is placed in another tree or under another parent than this shell`)
   }
 
@@ -1119,6 +1143,12 @@ export class RelayCore {
    * whether a claim placed under `parent` restarts `row`: it lands where `row` sits (under `row`'s parent, or a root with no placement), or on
    * `row` itself from `row`'s own process; never under `row` or elsewhere in its tree
    */
+  /** a local row held only by connections whose harness process exited, as a shim that outlived its harness leaves it */
+  private outlived(row: EndpointRow): boolean {
+    const pid = Number(/^pid:(\d+):/.exec(row.process ?? "")?.[1])
+    return row.connections > 0 && pid > 0 && this.localRow(row) && !this.alive(pid)
+  }
+
   private restarts(row: EndpointRow, parent: EndpointRow | null, process: string | null): boolean {
     if (parent?.id === row.id) return process !== null && row.process !== null && sameHarness(row.process, process)
     return (parent?.id ?? null) === row.parent_ep || (parent === null && row.linked !== null)
@@ -1132,7 +1162,7 @@ export class RelayCore {
     const spent = this.spentGrant(scope)
     if (spent?.used_by !== row.id) return false
     const lineage = this.lineageParent(scope.lineage)
-    if (!lineage) return row.harness === claimant.harness && spent.spent_cwd !== null && spent.spent_cwd === claimant.cwd
+    if (!lineage) return harnessFits(row.harness, claimant.harness) && spent.spent_cwd !== null && spent.spent_cwd === claimant.cwd
     return this.restarts(row, lineage, claimant.process) || this.ancestorsOf(row).includes(lineage.id)
   }
 
@@ -1300,7 +1330,7 @@ export class RelayCore {
       endpoint,
     )
     const row = this.mustEndpoint(endpoint)
-    if (!options.settle || presenceOf(row, now) !== "offline" || (row.status_state !== "working" && row.status_state !== "waiting")) return false
+    if (!options.settle || shownPresence(row, now) !== "offline" || (row.status_state !== "working" && row.status_state !== "waiting")) return false
     this.sql.all(`UPDATE endpoints SET status_state = NULL, status_note = NULL WHERE id = ?`, endpoint)
     return true
   }
@@ -1317,6 +1347,7 @@ export class RelayCore {
       `UPDATE endpoints SET connections = 0, hook_seen = CASE WHEN kind = 'agent' AND hook_ended IS NULL THEN MAX(COALESCE(hook_seen, 0), ?) ELSE hook_seen END WHERE connections > 0`,
       this.now() - (LIMITS.hookIdleS - LIMITS.restartGraceS) * 1000,
     )
+    this.sql.all(`UPDATE endpoints SET wakers = 0, waker_left = ? WHERE wakers > 0`, this.now())
   }
 
   whoami(endpoint: string): EndpointView {
@@ -1346,7 +1377,7 @@ export class RelayCore {
     const shown = viewer ? new Set(this.visibleRows(viewer).map((row) => row.id)) : undefined
     const peeker = viewer ?? (filters.peekable === true ? this.byHandle(HUMAN_HANDLE)! : undefined)
     return this.listed()
-      .filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff)
+      .filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now))
       .filter((row) => !filters.harness || row.harness === filters.harness)
       .filter((row) => !filters.kind || row.kind === filters.kind)
       .filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human"))
@@ -1463,6 +1494,21 @@ export class RelayCore {
     return true
   }
 
+  /**
+   * a connection that set the endpoint's wake starts (`live`) or stops counting as its waker. A hook's (`grace`) still counts for
+   * LIMITS.restartGraceS after it closes, while its harness starts the next one
+   */
+  waker(endpoint: string, live: boolean, options: { grace?: boolean } = {}): void {
+    if (live) this.sql.all(`UPDATE endpoints SET wakers = wakers + 1 WHERE id = ?`, endpoint)
+    else
+      this.sql.all(
+        `UPDATE endpoints SET wakers = MAX(wakers - 1, 0), waker_left = CASE WHEN ? THEN ? ELSE waker_left END WHERE id = ?`,
+        options.grace ? 1 : 0,
+        this.now(),
+        endpoint,
+      )
+  }
+
   /**
    * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
    * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
@@ -1782,7 +1828,7 @@ export class RelayCore {
     const dark = recipients.filter(
       (r) =>
         r.kind === "agent" &&
-        presenceOf(r, now) === "offline" &&
+        shownPresence(r, now) === "offline" &&
         (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || (r.session === null && r.token_hash === null && r.hook_ended !== null)) &&
         !this.unjoinedSpawn(sender, r.handle, now),
     )
@@ -2042,7 +2088,7 @@ export class RelayCore {
   private reach(sender: EndpointRow, recipient: EndpointRow, offline: boolean, now: number): Reach | undefined {
     if (recipient.kind !== "agent" || !this.localRow(recipient)) return undefined
     const done = recipient.status_state === "done"
-    if ((done || presenceOf(recipient, now) === "offline") && this.unjoinedSpawn(sender, recipient.handle, now)) return "starting"
+    if ((done || shownPresence(recipient, now) === "offline") && this.unjoinedSpawn(sender, recipient.handle, now)) return "starting"
     if (done) return "ended"
     return offline ? "offline" : "running"
   }
@@ -2495,7 +2541,7 @@ export class RelayCore {
         continue
       }
       const row = this.byId(grant.used_by)
-      if (!row || row.status_state === "done" || (presenceOf(row, now) === "offline" && (grant.handback !== null || !pid || !this.alive(pid)))) continue
+      if (!row || row.status_state === "done" || (shownPresence(row, now) === "offline" && (grant.handback !== null || !pid || !this.alive(pid)))) continue
       workers.set(row.id, row)
       if (grant.pushed_at !== null && grant.pushed_at > now - LIMITS.pushGapS * 1000) paced.add(row.id)
     }
@@ -2897,10 +2943,10 @@ export class RelayCore {
       .filter((row) =>
         present
           ? present.includes(row.id)
-          : presenceOf(row, now) !== "offline" || Math.max(row.last_seen ?? 0, row.hook_seen ?? 0, row.hook_ended ?? 0) >= asked.created_at,
+          : shownPresence(row, now) !== "offline" || Math.max(row.last_seen ?? 0, row.hook_seen ?? 0, row.hook_ended ?? 0) >= asked.created_at,
       )
     const gone = (row: EndpointRow): boolean =>
-      presenceOf(row, now) === "offline" &&
+      shownPresence(row, now) === "offline" &&
       ((row.hook_ended ?? 0) >= asked.created_at || row.status_state === "done" || now - Math.max(row.last_seen ?? 0, row.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS)
     if (!rows.length || !rows.every(gone)) return null
     return rows.map((row) => ({ address: this.address(row), state: row.status_state as StatusState | null }))
@@ -3014,7 +3060,7 @@ export class RelayCore {
     for (const row of this.sql.all<EndpointRow>(
       `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND status_state IN ('working', 'waiting')`,
     )) {
-      if (this.localRow(row) && presenceOf(row, now) === "offline")
+      if (this.localRow(row) && shownPresence(row, now) === "offline")
         this.sql.all(`UPDATE endpoints SET status_state = NULL, status_note = NULL WHERE id = ?`, row.id)
     }
   }
@@ -5074,7 +5120,7 @@ export class RelayCore {
 
   /** with `shown`, the ids a viewer sees: a parent outside it is null */
   protected view(row: EndpointRow, shown?: Set<string>): EndpointView {
-    const presence = presenceOf(row, this.now())
+    const presence = shownPresence(row, this.now())
     return {
       id: row.id,
       address: this.address(row),
@@ -5310,6 +5356,11 @@ const ANY_PROCESS_KEY = /^pid:\d+(:[A-Za-z0-9:-]{1,64})?$/
  * whether a connecting claim from the harness process `key` may join a session endpoint: no connection holds it, the harness process that last
  * claimed it claims again, and, once a connection held it (a token was handed out), with the same full key, which a recycled pid cannot match
  */
+/** a claim from the very harness process that holds the live `row`, such as a session it restarted in process */
+function reclaims(row: EndpointRow, key: string | null): boolean {
+  return row.connections > 0 && key !== null && row.process === key && PROCESS_KEY.test(key)
+}
+
 function sameProcess(row: EndpointRow, key: string | null): boolean {
   if (row.connections > 0 || key === null || row.process === null) return false
   return row.token_hash === null ? sameHarness(row.process, key) : row.process === key && PROCESS_KEY.test(key)
@@ -5374,6 +5425,17 @@ function presenceOf(row: EndpointRow, now: number): Presence {
   return row.hook_seen >= now - LIMITS.hookIdleS * 1000 ? "idle" : "offline"
 }
 
+/** a wake with a live waker, or a hook waker that left within LIMITS.restartGraceS */
+function waking(row: EndpointRow, now: number): boolean {
+  return wakeOf(row) !== null && (row.wakers > 0 || (row.waker_left ?? 0) >= now - LIMITS.restartGraceS * 1000)
+}
+
+/** the presence an endpoint shows: one its waker can wake is at least idle, though its session's own presence decayed */
+function shownPresence(row: EndpointRow, now: number): Presence {
+  const presence = presenceOf(row, now)
+  return presence === "offline" && waking(row, now) ? "idle" : presence
+}
+
 function pairKey(a: string, b: string): string {
   return a < b ? `${a}|${b}` : `${b}|${a}`
 }

package/src/protocol.ts

@@ -34,7 +34,7 @@ export const LIMITS = {
   hookEndedGraceS: 30,
   restartGraceS: 60,
   injectMessages: 5,
-  injectBytes: 4096,
+  injectBytes: 7168,
   pushBytes: 20480,
   /** the stops a session's push may continue between two prompts */
   pushes: 20,
@@ -144,6 +144,21 @@ export function validHarness(harness: string): boolean {
   return HARNESS.test(harness)
 }
 
+/** harness names of the path a claim came by (a bare CLI, hook or MCP shim), not of the agent behind it */
+export const GENERIC_HARNESSES: ReadonlySet<string> = new Set(["cli", "hook", "mcp", "shell"])
+
+const generic = (harness: string | null): boolean => harness === null || GENERIC_HARNESSES.has(harness)
+
+/** whether a claim of harness `claimed` may take a row of harness `held`: the same harness, or a generic row, which heals to the claim's */
+export function harnessFits(held: string | null, claimed: string): boolean {
+  return held === claimed || generic(held)
+}
+
+/** the harness a claimed row keeps: the claim's, except that a generic claim never replaces a known harness */
+export function keptHarness(held: string | null, claimed: string): string {
+  return generic(claimed) && !generic(held) ? held! : claimed
+}
+
 export interface Claim {
   handle?: string
   harness?: string