sentinelayer-cli 0.41.0 → 0.42.0

package/src/session/stream.js

@@ -8,6 +8,7 @@ import {
   sessionEventIdentityKeys,
 } from "./event-identity.js";
 import { enrichEventWithMentions } from "./mentions.js";
+import { messageRevision, projectSessionMessageEdits } from "./message-edits.js";
 import { resolveSessionPaths } from "./paths.js";
 import { redactEventPayload } from "./redact.js";
 import { fetchSessionFromApi, listSessionsFromApi, syncSessionEventToApi } from "./sync.js";
@@ -287,6 +288,23 @@ async function releaseLock(lockPath) {
   await fsp.rm(lockPath, { recursive: true, force: true }).catch(() => {});
 }
 
+// Creation and append must coordinate on the SAME lock. In particular, two
+// billing writers may both observe a missing session before either creates it.
+// The callback must not append (append acquires this lock independently).
+export async function withSessionStreamLock(sessionId, operation, {
+  targetPath = process.cwd(),
+  timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+} = {}) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  await fsp.mkdir(paths.sessionDir, { recursive: true });
+  await acquireLock(paths.lockPath, { timeoutMs });
+  try {
+    return await operation();
+  } finally {
+    await releaseLock(paths.lockPath);
+  }
+}
+
 async function readEventsFromFile(filePath) {
   try {
     const raw = await fsp.readFile(filePath, "utf-8");
@@ -359,7 +377,8 @@ function eventsShareIdentity(left = {}, right = {}) {
 }
 
 async function appendOrMergeCurrentStreamEvent(paths, canonicalEvent, { mergeExisting = false } = {}) {
-  if (!mergeExisting) {
+  // Keep prior revisions in the raw audit log. Readers project the latest body.
+  if (!mergeExisting || messageRevision(canonicalEvent) > 1) {
     await fsp.appendFile(paths.streamPath, `${JSON.stringify(canonicalEvent)}\n`, "utf-8");
     return;
   }
@@ -427,6 +446,7 @@ export async function appendToStream(
     maxEvents = DEFAULT_MAX_STREAM_EVENTS,
     syncRemote = true,
     awaitRemoteSync = false,
+    lockTimeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
     mergeExisting = false,
   } = {}
 ) {
@@ -457,7 +477,7 @@ export async function appendToStream(
   const nowIso = new Date().toISOString();
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_MAX_STREAM_EVENTS);
 
-  await acquireLock(paths.lockPath);
+  await acquireLock(paths.lockPath, { timeoutMs: lockTimeoutMs });
   try {
     await fsp.mkdir(paths.sessionDir, { recursive: true });
     await appendOrMergeCurrentStreamEvent(paths, canonicalEvent, { mergeExisting });
@@ -490,7 +510,7 @@ export async function readStream(
   { tail = 20, since = null, targetPath = process.cwd() } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
-  const events = await readAllEvents(paths);
+  const events = projectSessionMessageEdits(await readAllEvents(paths));
   const filtered = filterBySince(events, since);
   const normalizedTail = Number(tail);
   if (!Number.isFinite(normalizedTail) || normalizedTail <= 0) {

package/src/session/sync.js

@@ -7,6 +7,13 @@ import { randomUUID } from "node:crypto";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { createAgentEvent } from "../events/schema.js";
 import { isSessionControlEvent } from "./control-events.js";
+import { createSessionMutationHeaders } from "./invitations.js";
+import { messageRevision } from "./message-edits.js";
+import { installTestEgressGuard } from "../net/test-egress-guard.js";
+
+// No-op outside tests; inside a test process (or a child it spawned) every fetch
+// to a non-loopback host is refused before a socket opens.
+installTestEgressGuard();
 
 const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
 const DEFAULT_SYNC_TIMEOUT_MS = 5_000;
@@ -327,6 +334,11 @@ function isApiHostAllowed(urlString) {
 function resolveApiBaseUrl(session = {}) {
   const apiUrl = normalizeString(session.apiUrl) || DEFAULT_API_BASE_URL;
   const normalized = apiUrl.replace(/\/+$/, "");
+  if (!isApiHostAllowed(normalized) && session.source === "session_admission") {
+    // An admission credential is bound to the API that issued it. Redirecting it to
+    // the default host would hand it to an API it was never meant for: refuse.
+    throw new Error("Refusing to send an agent admission credential to a host other than the API that issued it.");
+  }
   if (!isApiHostAllowed(normalized)) {
     // Reject tampered session.apiUrl and fall back to the default.
     // Caller will see API calls land on the canonical host, not an attacker's.
@@ -634,12 +646,12 @@ async function readResponseJsonSafely(response, timeoutMs = DEFAULT_SYNC_TIMEOUT
   }
 }
 
-async function fetchJsonWithFullTimeout(
+export async function fetchJsonWithFullTimeout(
   url,
   options,
   timeoutMs,
   fetchImpl = fetchWithTimeout,
-  { readErrorBody = false } = {},
+  { readErrorBody = false, readSuccessBody = true, errorBodyStatuses = [] } = {},
 ) {
   const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
   const controller = new AbortController();
@@ -660,13 +672,15 @@ async function fetchJsonWithFullTimeout(
   );
 
   let payload = {};
-  if (response?.ok || readErrorBody) {
+  if ((response?.ok && readSuccessBody) || readErrorBody || errorBodyStatuses.includes(response?.status)) {
     const elapsedMs = Math.max(0, Date.now() - startedAtMs);
     const remainingMs = Math.max(1, resolvedTimeoutMs - elapsedMs);
     payload = await readResponseJsonWithTimeout(response, remainingMs, {
       fallback: {},
       onTimeout: () => abortRequestController(controller, "response_body_timeout"),
     });
+  } else {
+    cancelResponseBody(response);
   }
   return { response, payload };
 }
@@ -867,6 +881,18 @@ function buildHumanRelayEvent(sessionId, message = {}) {
     agentId,
     sessionId,
     ts,
+    // The compatibility human-poll lane must preserve canonical revision and
+    // identity too; otherwise an edited body is mistaken for a fresh directive
+    // when its paired durable edit notification has not reached this poller.
+    id: message.eventId || message.event_id || undefined,
+    eventId: message.eventId || message.event_id || undefined,
+    cursor: message.cursor || undefined,
+    sequenceId: message.sequenceId ?? message.sequence_id,
+    messageRevision: messageRevision(message),
+    editedAt: message.editedAt,
+    editedBy: message.editedBy,
+    canEdit: message.canEdit,
+    revisionEvidence: message.revisionEvidence,
     payload: {
       message: sanitization.message,
       channel: "session",
@@ -982,9 +1008,14 @@ export async function syncSessionEventToApi(
     body: requestBody,
   };
   const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const deadlineMs = Date.now() + resolvedTimeoutMs;
+  const remainingMs = () => Math.max(1, deadlineMs - Date.now());
 
   try {
-    const response = await fetchImpl(endpoint, requestInit, resolvedTimeoutMs);
+    const { response, payload: forbiddenBody } = await fetchJsonWithFullTimeout(
+      endpoint, requestInit, remainingMs(), fetchImpl,
+      { readSuccessBody: false, errorBodyStatuses: [403] },
+    );
 
     if (response && response.ok) {
       recordCircuitSuccess(outboundCircuit);
@@ -1000,7 +1031,7 @@ export async function syncSessionEventToApi(
     // their agents "talking" locally while the API has zero record. We attempt
     // the grant once per agentId per process, then retry the event POST once.
     if (response && response.status === 403) {
-      const body = await readResponseJsonSafely(response);
+      const body = forbiddenBody;
       if (isIdentityForgeryBody(body)) {
         const agentId = normalizeString(event?.agent?.id);
         if (!agentId || isReservedAgentIdForGrant(agentId)) {
@@ -1022,7 +1053,7 @@ export async function syncSessionEventToApi(
         const grantEndpoint = `${apiBaseUrl}/api/v1/sessions/agent-grants`;
         let grantResponse = null;
         try {
-          grantResponse = await fetchImpl(
+          ({ response: grantResponse } = await fetchJsonWithFullTimeout(
             grantEndpoint,
             {
               method: "POST",
@@ -1035,8 +1066,8 @@ export async function syncSessionEventToApi(
                 role: grantRole,
               }),
             },
-            resolvedTimeoutMs
-          );
+            remainingMs(), fetchImpl, { readSuccessBody: false },
+          ));
         } catch (grantError) {
           recordCircuitFailure(outboundCircuit, normalizedNowMs);
           return {
@@ -1060,7 +1091,9 @@ export async function syncSessionEventToApi(
         // Retry the original event POST exactly once.
         let retryResponse;
         try {
-          retryResponse = await fetchImpl(endpoint, requestInit, resolvedTimeoutMs);
+          ({ response: retryResponse } = await fetchJsonWithFullTimeout(
+            endpoint, requestInit, remainingMs(), fetchImpl, { readSuccessBody: false },
+          ));
         } catch (retryError) {
           recordCircuitFailure(outboundCircuit, normalizedNowMs);
           return {
@@ -1156,7 +1189,7 @@ async function syncSessionAuxPayload(
   const apiBaseUrl = resolveApiBaseUrl(session);
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}${pathSuffix}`;
   try {
-    const response = await fetchImpl(
+    const { response } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "POST",
@@ -1169,7 +1202,9 @@ async function syncSessionAuxPayload(
           source: "cli",
         }),
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
+      { readSuccessBody: false },
     );
     if (!response || !response.ok) {
       recordCircuitFailure(outboundCircuit, normalizedNowMs);
@@ -2755,6 +2790,88 @@ export async function fetchSessionPinnedMessages(
   };
 }
 
+// Native edits never fall back to POST /events or mutate an optimistic local row.
+export async function editSessionMessage(sessionId, {
+  targetSequenceId = null,
+  targetMessageId = "",
+  targetActionId = "",
+  text,
+  expectedRevision = null,
+  agentId = "",
+  idempotencyKey = "",
+  targetPath = process.cwd(),
+  timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+  signal,
+  resolveAuthSession = resolveActiveAuthSession,
+  fetchImpl = fetchWithTimeout,
+  nowMs = Date.now,
+} = {}) {
+  const sid = normalizeString(sessionId);
+  const sequence = Number(targetSequenceId);
+  const replyId = normalizeString(targetActionId);
+  let messageId = normalizeString(targetMessageId);
+  let revision = expectedRevision === null || expectedRevision === undefined ? null : Number(expectedRevision);
+  const validSequence = Number.isSafeInteger(sequence) && sequence > 0;
+  const mutationKey = normalizeString(idempotencyKey) || `sl-message-edit-${randomUUID()}`;
+  if (!sid || typeof text !== "string" || !text.trim() || (!replyId && !messageId && !validSequence) ||
+      (revision !== null && (!Number.isSafeInteger(revision) || revision <= 0)) || mutationKey.length > 128) {
+    return { ok: false, reason: "invalid_input" };
+  }
+  if (String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1") return { ok: false, reason: "remote_sync_disabled_env" };
+  const timestamp = Number(nowMs()) || Date.now();
+  if (isCircuitOpen(outboundCircuit, timestamp)) return { ok: false, reason: "circuit_breaker_open" };
+  let auth;
+  try { auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false }); }
+  catch { return { ok: false, reason: "no_session" }; }
+  if (!auth?.token) return { ok: false, reason: "not_authenticated" };
+  const base = `${resolveApiBaseUrl(auth)}/api/v1/sessions/${encodeURIComponent(sid)}`;
+  const headers = { Authorization: `Bearer ${auth.token}` };
+  const failure = (response, payload) => {
+    const code = normalizeString(payload?.detail?.code || payload?.error?.code || payload?.code);
+    // Client/schema/ownership conflicts are terminal and must not poison unrelated writes.
+    if (!response || response.status >= 500) recordCircuitFailure(outboundCircuit, timestamp);
+    return { ok: false, reason: code || `api_${response?.status || "no_response"}`, status: response?.status || null };
+  };
+  try {
+    // Sequence resolution and omitted-revision lookup are one authenticated GET.
+    if ((!replyId && !messageId) || revision === null) {
+      const resource = replyId ? `replies/${encodeURIComponent(replyId)}` : messageId
+        ? `messages/${encodeURIComponent(messageId)}` : `messages/by-sequence/${sequence}`;
+      const authorQuery = normalizeString(agentId) ? `?agentId=${encodeURIComponent(normalizeString(agentId))}` : "";
+      const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}${authorQuery}`, { method: "GET", headers, signal }, timeoutMs, fetchImpl, { readErrorBody: true });
+      if (!response?.ok || payload?.ok === false) return failure(response, payload);
+      const current = replyId ? payload?.reply : payload?.event;
+      const fetchedRevision = Number(current?.messageRevision ?? 1);
+      if (!current?.id || (replyId && current.id !== replyId) || !Number.isSafeInteger(fetchedRevision) || fetchedRevision <= 0) return { ok: false, reason: "invalid_edit_target" };
+      if (current.canEdit === false) return { ok: false, reason: "MESSAGE_EDIT_FORBIDDEN", status: 403 };
+      if (!replyId) messageId = current.id;
+      if (revision === null) revision = fetchedRevision;
+    }
+    const resource = replyId ? `replies/${encodeURIComponent(replyId)}` : `messages/${encodeURIComponent(messageId)}`;
+    const body = { text, expectedRevision: revision, ...(normalizeString(agentId) ? { agentId: normalizeString(agentId) } : {}) };
+    const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}`, {
+      method: "PATCH",
+      headers: {
+        ...createSessionMutationHeaders({ bearerToken: auth.token, sessionId: sid, routeId: replyId
+          ? "PATCH /api/v1/sessions/{session_id}/replies/{action_id}"
+          : "PATCH /api/v1/sessions/{session_id}/messages/{message_id}", idempotencyKey: mutationKey }),
+        "Content-Type": "application/json", "Idempotency-Key": mutationKey,
+      },
+      body: JSON.stringify(body),
+      signal,
+    }, timeoutMs, fetchImpl, { readErrorBody: true });
+    if (!response?.ok || payload?.ok !== true) return failure(response, payload);
+    const current = replyId ? payload.reply : payload.event;
+    const currentRevision = Number(current?.messageRevision ?? 1);
+    if (!current?.id || current.id !== (replyId || messageId) || !Number.isSafeInteger(currentRevision) || currentRevision <= 0) return { ok: false, reason: "invalid_edit_response" };
+    recordCircuitSuccess(outboundCircuit);
+    return { ok: true, changed: Boolean(payload.changed), replayed: Boolean(payload.replayed), event: payload.event || null, reply: payload.reply || null, notification: payload.notification || null };
+  } catch (error) {
+    recordCircuitFailure(outboundCircuit, timestamp);
+    return { ok: false, reason: normalizeString(error?.message) || "message_edit_failed" };
+  }
+}
+
 export async function createSessionMessageAction(
   sessionId,
   {

package/src/session/tickets.js

@@ -0,0 +1,316 @@
+// tickets.js — the room's shared backlog from the CLI: list, claim, renew, release,
+// submit, and the ticket event feed (API "Ticket Lease Contract (T2)").
+//
+// Credentials: every call resolves auth with resolveActiveAuthSession. Inside an
+// admitted agent's command (the runCli choke point), that is the agent's admission
+// credential and never the human token, so a ticket is claimed AS the agent.
+//
+// Lease state: a claim's { leaseId, fence, version, expiresAt } is kept per
+// (session, ticket, identity) in a local file. Only a MISSING file means "no lease
+// held here"; an unreadable one refuses, never reads as absent.
+//
+// Lost responses: a write's Idempotency-Key is stored BEFORE the request is sent. If
+// the response is lost, re-running the same command reuses that key, and the server
+// replays the original result instead of performing the operation again.
+
+import { randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function segment(value, label) {
+  const text = normalizeString(value).toLowerCase();
+  if (!/^[a-z0-9][a-z0-9._:-]{0,63}$/.test(text)) throw new Error(`${label} is not a valid identifier.`);
+  return text.replace(/:/g, "%3a");
+}
+
+export function ticketLeasePath(sessionId, ticketId, identity, { homeDir } = {}) {
+  return path.join(
+    homeDir || os.homedir(),
+    ".sentinelayer",
+    "agents",
+    segment(identity, "identity"),
+    "tickets",
+    segment(sessionId, "sessionId"),
+    `${segment(ticketId, "ticketId")}.json`
+  );
+}
+
+async function readState(filePath) {
+  let raw;
+  try {
+    raw = await fsp.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw new Error(`The local ticket lease state at ${filePath} is unreadable; refusing to guess.`);
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+    return parsed;
+  } catch {
+    throw new Error(`The local ticket lease state at ${filePath} is unreadable; refusing to guess.`);
+  }
+}
+
+async function writeState(filePath, state) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.${randomUUID()}.tmp`;
+  await fsp.writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await fsp.rename(tmp, filePath);
+}
+
+async function auth(targetPath, resolveAuthSession) {
+  const session = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false });
+  if (!session?.token || !session?.apiUrl) throw new Error("Not authenticated for this session.");
+  return { token: session.token, apiUrl: normalizeString(session.apiUrl).replace(/\/+$/, "") };
+}
+
+function ticketsUrl(apiUrl, sessionId, suffix = "") {
+  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/tickets${suffix}`;
+}
+
+/** The Idempotency-Key for this logical write: reused until its response is stored. */
+async function operationKey(statePath, operation, fingerprint) {
+  const state = (await readState(statePath)) || {};
+  const pending = state.pending;
+  if (pending && pending.operation === operation && pending.fingerprint === fingerprint && pending.key) {
+    return { key: pending.key, state };
+  }
+  const key = `${operation}-${randomUUID()}`;
+  const next = { ...state, pending: { operation, fingerprint, key } };
+  await writeState(statePath, next);
+  return { key, state: next };
+}
+
+function leaseState(response) {
+  return {
+    version: 1,
+    leaseId: response.lease.leaseId,
+    fence: response.lease.fence,
+    ticketVersion: response.version,
+    expiresAt: response.lease.expiresAt,
+  };
+}
+
+const SNAPSHOT_PAGE = 200;
+const SNAPSHOT_MAX_PAGES = 50;
+
+function malformedSnapshot(reason) {
+  return new Error(`The ticket snapshot is malformed (${reason}); refusing a partial list.`);
+}
+
+/**
+ * One snapshot page, validated before anything in it is believed. The snapshot is keyset by
+ * ticket id: ids on a page are STRICTLY ascending and above the previous continuation (so
+ * none repeats), and the continuation is exactly the LAST id returned -- a token that jumps
+ * ahead would silently skip every ticket in between. Anything else is not a complete list.
+ */
+function validatedSnapshotPage(body, { first, afterId }) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw malformedSnapshot("a page is not an object");
+  if (!Array.isArray(body.items)) throw malformedSnapshot("a page has no items list");
+  if (typeof body.hasMore !== "boolean") throw malformedSnapshot("a page does not say whether there is more");
+  if (first && !(Number.isSafeInteger(body.cursor) && body.cursor >= 0)) {
+    throw malformedSnapshot("the first page has no room cursor to follow events from");
+  }
+  let previous = afterId;
+  for (const item of body.items) {
+    const id = item && typeof item === "object" ? item.id : null;
+    if (typeof id !== "string" || !id) throw malformedSnapshot("a ticket has no id");
+    if (previous && !(id > previous)) throw malformedSnapshot("ticket ids are not in ascending order");
+    previous = id;
+  }
+  if (body.hasMore) {
+    if (!body.items.length) throw malformedSnapshot("an empty page claims there is more");
+    const next = body.nextAfterId;
+    if (typeof next !== "string" || !next) throw malformedSnapshot("there is more but no way to continue");
+    if (next !== previous) throw malformedSnapshot("the continuation is not the last ticket returned");
+  }
+  return body;
+}
+
+/**
+ * The room's COMPLETE backlog, from GET /tickets/snapshot paged to the end. The board read
+ * (GET /tickets) is a bounded, newest-first page: filtering it for "available" could miss
+ * claimable work beyond the page. `cursor` is the FIRST page's room cursor, taken with that
+ * page; `sl session ticket events --after <cursor>` continues from exactly there. A snapshot
+ * that cannot be completed is refused, never returned partial.
+ */
+export async function listTickets(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    available = false,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestRead = requestJson,
+    pageSize = SNAPSHOT_PAGE,
+    maxPages = SNAPSHOT_MAX_PAGES,
+  } = {}
+) {
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  const items = [];
+  let cursor = null;
+  let afterId = null;
+  let complete = false;
+  for (let page = 0; page < maxPages && !complete; page += 1) {
+    const query = new URLSearchParams({ limit: String(pageSize) });
+    if (afterId) query.set("afterId", afterId);
+    const body = validatedSnapshotPage(
+      await requestRead(`${ticketsUrl(apiUrl, sessionId, "/snapshot")}?${query}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+      }),
+      { first: page === 0, afterId },
+    );
+    if (page === 0) cursor = body.cursor; // ONLY the first page's cursor is the baseline
+    items.push(...body.items);
+    if (!body.hasMore) complete = true;
+    else afterId = body.nextAfterId;
+  }
+  if (!complete) {
+    throw new Error(`The room has more than ${maxPages * pageSize} tickets; refusing a partial list.`);
+  }
+  // Newest first for people; the snapshot itself is in id order.
+  items.sort((a, b) => String(b.createdAt || "").localeCompare(String(a.createdAt || "")) || String(a.id).localeCompare(String(b.id)));
+  // Available = claimable by someone now: open, or working with an expired lease.
+  // Never blocked work: the MVP has no dependencies, and blocked is never available.
+  const filtered = available
+    ? items.filter((t) => t.status === "open" || (t.status === "working" && t.lease && !t.lease.live))
+    : items;
+  return { items: filtered, cursor, count: filtered.length, complete: true };
+}
+
+export async function ticketEvents(
+  sessionId,
+  { after = 0, targetPath = process.cwd(), resolveAuthSession = resolveActiveAuthSession, requestRead = requestJson } = {}
+) {
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  return requestRead(`${ticketsUrl(apiUrl, sessionId, "/events")}?after=${encodeURIComponent(String(after))}`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+
+async function mutate(url, { token, key, operation, body, requestMutation }) {
+  return requestMutation(url, {
+    method: "POST",
+    operationName: `session.ticket_${operation}`,
+    idempotencyKey: key,
+    headers: { Authorization: `Bearer ${token}`, "Idempotency-Key": key },
+    body,
+  });
+}
+
+export async function claimTicket(
+  sessionId,
+  ticketId,
+  {
+    identity,
+    expectedVersion = null,
+    targetPath = process.cwd(),
+    homeDir,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {}
+) {
+  const statePath = ticketLeasePath(sessionId, ticketId, identity, { homeDir });
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  const { key } = await operationKey(statePath, "claim", String(expectedVersion ?? "any"));
+  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/claim`), {
+    token, key, operation: "claim", requestMutation,
+    body: expectedVersion == null ? {} : { expectedVersion: Number(expectedVersion) },
+  });
+  // The lease is recorded here only if the server says it is held by the identity that
+  // asked: an agent by its own id, a person as a human. Anything else is not this lease.
+  const holder = response?.ticket?.lease;
+  const heldByIdentity =
+    identity === "human" ? holder?.holderKind === "human" : holder?.holderKind === "agent" && holder?.holder === identity;
+  if (!heldByIdentity) {
+    throw new Error(
+      `The server recorded this lease for ${holder?.holderKind || "nobody"} "${holder?.holder || ""}", not for "${identity}". ` +
+        "Nothing was recorded locally; release it from the web if it is not yours."
+    );
+  }
+  await writeState(statePath, leaseState(response));
+  return response;
+}
+
+async function heldLease(statePath) {
+  const state = await readState(statePath);
+  if (!state || !state.leaseId) {
+    throw new Error("This identity holds no lease on that ticket here. Claim it first.");
+  }
+  return state;
+}
+
+export async function renewTicketLease(
+  sessionId,
+  ticketId,
+  { identity, targetPath = process.cwd(), homeDir, resolveAuthSession = resolveActiveAuthSession, requestMutation = requestJsonMutation } = {}
+) {
+  const statePath = ticketLeasePath(sessionId, ticketId, identity, { homeDir });
+  const held = await heldLease(statePath);
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  const { key } = await operationKey(statePath, "renew", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
+  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/lease/renew`), {
+    token, key, operation: "renew", requestMutation, body: { leaseId: held.leaseId, fence: held.fence },
+  });
+  await writeState(statePath, leaseState(response));
+  return response;
+}
+
+export async function releaseTicketLease(
+  sessionId,
+  ticketId,
+  { identity, reason = null, targetPath = process.cwd(), homeDir, resolveAuthSession = resolveActiveAuthSession, requestMutation = requestJsonMutation } = {}
+) {
+  const statePath = ticketLeasePath(sessionId, ticketId, identity, { homeDir });
+  const held = await heldLease(statePath);
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  const { key } = await operationKey(statePath, "release", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
+  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/lease/release`), {
+    token, key, operation: "release", requestMutation,
+    body: { leaseId: held.leaseId, fence: held.fence, expectedVersion: held.ticketVersion, ...(reason ? { reason } : {}) },
+  });
+  await fsp.rm(statePath, { force: true });
+  return response;
+}
+
+export async function submitTicket(
+  sessionId,
+  ticketId,
+  {
+    identity,
+    implementationSha = null,
+    evidence = [],
+    targetPath = process.cwd(),
+    homeDir,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {}
+) {
+  const statePath = ticketLeasePath(sessionId, ticketId, identity, { homeDir });
+  const held = await heldLease(statePath);
+  const { token, apiUrl } = await auth(targetPath, resolveAuthSession);
+  const { key } = await operationKey(statePath, "submit", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
+  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/submit`), {
+    token, key, operation: "submit", requestMutation,
+    body: {
+      leaseId: held.leaseId,
+      fence: held.fence,
+      expectedVersion: held.ticketVersion,
+      ...(implementationSha ? { implementationSha } : {}),
+      evidence,
+    },
+  });
+  await fsp.rm(statePath, { force: true });
+  return response;
+}

package/src/session/title-sync.js

@@ -38,6 +38,7 @@ export async function pushSessionTitleToApi(
     timeoutMs = DEFAULT_TITLE_SYNC_TIMEOUT_MS,
     maxRetries = 1,
     retryDelayMs = DEFAULT_TITLE_SYNC_RETRY_DELAY_MS,
+    autoRotate = true,
     resolveAuthSession = resolveActiveAuthSession,
     requestMutation = requestJsonMutation,
     recordRemoteTitleSync = recordSessionRemoteTitleSync,
@@ -63,7 +64,7 @@ export async function pushSessionTitleToApi(
     const session = await resolveAuthSession({
       cwd: targetPath,
       env,
-      autoRotate: true,
+      autoRotate,
     });
     if (!session?.token || !session?.apiUrl) {
       await recordRemoteTitleSync(normalizedSessionId, {