@open-everywhere/core 0.1.0

package/agent/tools/cancel_routine.ts

@@ -0,0 +1,133 @@
+// cancel_routine PROPOSES stopping a routine on this surface by its id. Cancelling REMOVES a standing behaviour the surface relies on, and an injected turn that silently cancels the watch guarding a system is the mirror of an injected create — so this validates and freezes the exact routine id and its trigger description, posts a card, and the durable removal happens on a human's click. The dispatcher's own self-disable of broken routines is a separate path, unattended by design.
+// 🔴 A FIRE CANNOT PROPOSE ONE: the gate below asks for the ACTING principal, so it is unsatisfiable inside a triggered fire. The card is not a sufficient control on its own — a card's persuasive weight is the human NAME on its "asked by" line, and a fire binds as its routine's creator, so "Alice asked to stop the security watch" is a far better pretext for a wrong click than any machine identity. Nothing legitimate loses a verb: a routine that should stop firing self-disables host-side, a finished job completes itself, and a failing run declares its failure.
+
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { bindFrom } from "../identity/binding.js";
+import { actingPrincipalIdOf, unattendedOf } from "../access/request.js";
+import { resolvePartition } from "../memory/partition.js";
+import { proposalScopeKey } from "../channels/propose-scope.js";
+import { getRoutine } from "../routines/store.js";
+import { describeTrigger } from "../routines/routine.js";
+import { untrustedIngestedThisTurn } from "../access/taint-signal.js";
+import { requestApproval, autoApprovedNote } from "../approvals/flow.js";
+import { approvalPostDeps } from "./set_spend_limit.js";
+import { checkApprovalVenue, describeVenueRefusal, cardPostedPrefix, cardPostedTail } from "../approvals/card-venue.js";
+import { getConfig } from "../access/config.js";
+import { requireSessionContinuation } from "../spend/checkpoint.js";
+
+export default defineTool({
+  description:
+    "PROPOSE cancelling (deleting) a routine on this surface by its id. Get the id from list_routines. Use when asked to stop a scheduled job, watch, or subscription. This does NOT cancel on the spot: an approval card posts naming the exact routine, and it's removed only when a human confirms (cancelling removes a guardrail, so it's gated). The posted card IS the reply — do not add narration after this call. EXCEPT when this surface can't host a card: it then goes to a card-capable channel in the same domain, the `message` field names it, and you MUST relay that.",
+  inputSchema: z.object({
+    id: z.string().min(1).describe("The routine id, e.g. 'r-1a2b3c4d' (from list_routines)."),
+  }),
+  outputSchema: z.object({
+    // Gated: nothing is cancelled yet — an approval card was posted for a human to confirm.
+    pending: z.boolean(),
+    pendingId: z.string().optional(),
+    id: z.string(),
+    message: z.string(),
+    autoApproved: z.boolean().optional().describe("The approver chain lowered this verb: no card was posted and it has ALREADY run."),
+  }),
+  approval: never(),
+  async execute(input, ctx) {
+    // SOFT session cost checkpoint (OPE-62) — pause consequential work past a configured
+    // per-session threshold until a member confirms; no-op when unconfigured.
+    await requireSessionContinuation(ctx, "cancel_routine");
+    const p = resolvePartition(ctx);
+    // 🔴 THE ROOM THAT ASKED, NOT THE ROOM THAT ARRIVED LAST (OPE-1756). `p` above is the TURN's
+    // partition, and a turn that merged queued deliveries carries only the LAST delivery's auth —
+    // so on a turn answering two rooms it names the wrong one. The GOVERNED scope follows the
+    // ADDRESSED wake instead, through the same road the reply path uses; it falls back to `p` on
+    // every unknown, so a single-wake turn is unchanged.
+    // 🔴 THE MERGE ROAD IS UNREACHABLE ON eve 0.54.3; THIS READ IS STILL LIVE (OPE-2042). eve batches
+    // adjacent queued deliveries only when their full auth contexts match, and OE stamps a fresh
+    // per-delivery `oe_delivery_id` into `auth.attributes`, so two auth-carrying deliveries on one
+    // unified window never compare equal; only the caller-less task COMPLETION COHORT still folds,
+    // and it carries no `auth` at all. But the TURN's ctx names the wrong room WITHOUT any merge
+    // too: a turn woken by an INTERNAL wake — an approval decision, a completion — answers a
+    // conversation whose envelope is in the seat's shared context, through the reply fence's
+    // same-conversation and pending arms (`channels/unified-window.ts` `resolveAnswerableReplyTarget`,
+    // arms 3 and 4). Measured in production on 2026-08-15 (`docs/glossary.md`). So this read is
+    // LOAD-BEARING, not defensive. `scripts/coalesced-delivery-merge-assumption-test.ts` pins only
+    // the merge road's impossibility.
+    // 🔴 WHAT MOVES IS THE GOVERNANCE KEY ONLY. Anything else this tool derives from `p` — the memory
+    // tier, the card's venue walk, and any surface key frozen into the proposal's own `args` — keeps
+    // reading the TURN's partition, deliberately: those name what the act DOES and where this seat
+    // lives, while the scope key names who may approve it and which halt covers it. Moving the act's
+    // own target is a design choice this task does not hold.
+    const proposeScopeKey = await proposalScopeKey(ctx, p);
+    const id = input.id.trim();
+
+    // Load the routine now: it confirms the routine exists, and it FREEZES its trigger description onto the card, so the target is the real routine rather than something re-derived from model-visible state at click time.
+    const routine = await getRoutine(p.org, p.surfaceKey, id);
+    if (!routine) {
+      throw new Error(`No routine '${id}' on this surface — check the id with list_routines.`);
+    }
+    const description = describeTrigger(routine.trigger, routine.report);
+
+    // GATE (2026-07-11). Freeze (surfaceKey, id, description) and post an approval card; a
+    // human on the surface confirms the removal with a click (routine.cancel ActionKind does
+    // the removeRoutine). Same fail-closed gates as create_routine.
+    const binding = bindFrom(ctx);
+    // 🔴 THE ACTING principal (identity/binding.ts actingPrincipalId), never the bound one — see the
+    // header. `principalIdOf` here would be satisfied by a fire's attested creator, which is exactly
+    // the name that makes the card persuasive.
+    // principal-gate: presence — a card's persuasive weight IS the human name on it, so a fire proposing a
+    // cancellation would put a real person's name on a request they never made (OPE-272).
+    const requestedBy = actingPrincipalIdOf(ctx);
+    if (!requestedBy) {
+      throw new Error("cancel_routine needs a verified sender to gate the removal — a triggered routine fire has no acting sender (only the creator it is attributed to), and a fire may not propose removing a standing behaviour. Ask a person in this conversation to cancel it.");
+    }
+
+    // Where the card goes: this room when it can host one, otherwise a card-capable channel in the SAME domain.
+    // This also subsumes the old "couldn't resolve this channel's id" throw — a missing channelId on a card-capable surface simply means no own-room venue, which the walk reports precisely.
+    const venueResult = await checkApprovalVenue(binding, p, () => getConfig().loadDomains());
+    if ("refusal" in venueResult) {
+      throw new Error(describeVenueRefusal(venueResult.refusal, binding.platform, "cancel that routine"));
+    }
+    const venue = venueResult.venue;
+
+    // The proposing turn's taint, carried onto the card exactly as the edit and create verbs carry theirs.
+    // A REMOVAL is the direction that needs it most: an injected turn's likeliest ask is not "add a behaviour I can be seen arming" but "quietly stop the watch that would have noticed me".
+    const tainted = untrustedIngestedThisTurn();
+    const posted = await requestApproval(
+      {
+        org: p.org,
+        kind: "routine.cancel",
+        args: { org: p.org, partition: p, surfaceKey: p.surfaceKey, id, description, requestedBy, tainted },
+        scopeKey: proposeScopeKey,
+        domain: null,
+        requestedBy,
+        channelId: venue.channelId,
+        threadTs: venue.sameRoom ? binding.threadTs ?? null : null,
+        // Mint-frozen proposing-surface identity (task #105) — the TTL sweep's feedback target,
+        // and the VENUE's key because that is where the card actually is.
+        postedTo: venue.surfaceKey,
+        chain: { unattended: unattendedOf(ctx) },
+      },
+      approvalPostDeps(venue.platform, ctx),
+    );
+
+    // The chain can LOWER this verb (OPE-296): then no card exists and the cancel already ran, so
+    // the pending-voiced text below would be a lie. One subject phrase, two honest endings.
+    const subject = `cancel of routine ${id} (${description})${tainted ? " ⚠ tainted" : ""}`;
+    if (posted.autoApproved) {
+      return {
+        pending: false,
+        autoApproved: true,
+        pendingId: posted.id,
+        id,
+        message: autoApprovedNote(subject, posted.autoApproved),
+      };
+    }
+    return {
+      pending: true,
+      pendingId: posted.id,
+      id,
+      message: `${cardPostedPrefix(venue)} — ${subject} awaiting a human to confirm (pending ${posted.id}).${cardPostedTail(venue, "confirm the cancellation", posted)}`,
+    };
+  },
+});

package/agent/tools/capture_events.ts

@@ -0,0 +1,54 @@
+// capture_events opens a BOUNDED window in which a webhook's deliveries are retained, so a filter can be written against real traffic. ⭐ This is the ONLY way capture ever turns on: there is no default window, and creating a hook does not open one, because creation is not consent to retention — a hook nobody runs this on retains nothing, forever, which is why the feature can exist at all.
+// What is retained is NOT the payload body but the jq filter document. Headers never enter it, so a captured row cannot hold a signature or a bearer token, and the rendered summary never enters it, so no attacker-authored prose is retained — structural, rather than a redaction step someone could forget to run. Bounded three ways in code (row count, wall-clock however long a caller asks for, and an absolute retention sweep), and REFUSED by name for `trigger-only` hooks, whose whole purpose is keeping payloads away from humans.
+
+// Arming is audited, and the principal is passed from here: for the one verb in the tree that starts retaining a third party's bytes, "who turned this on" is the question the record exists to answer.
+
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { principalIdOf } from "../access/request.js";
+import { resolvePartition } from "../memory/partition.js";
+import { armCaptureWindow } from "../control/capture-window-read.js";
+import { CAPTURE_MAX_DELIVERIES, CAPTURE_MAX_WINDOW_MS } from "../operational/store.js";
+
+export default defineTool({
+  description:
+    "Turn on temporary recording of a webhook's incoming deliveries so their shape can be inspected with list_recent_events and a subscription filter written against real traffic. Use when someone wants a routine to fire on only some of a webhook's events and nobody knows what the sender's payload looks like. Recording is OFF until this is run, stops automatically, and keeps only a bounded number of recent deliveries. Refused for trigger-only webhooks, whose payloads are never retained by design.",
+  inputSchema: z.object({
+    source: z.string().min(1).describe("The webhook's source handle, e.g. 'deploy-status' (from list_webhooks)."),
+    minutes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(`How long to record for. Defaults to 15 and is capped at ${Math.round(CAPTURE_MAX_WINDOW_MS / 60_000)}.`),
+  }),
+  outputSchema: z.object({
+    ok: z.boolean(),
+    message: z.string(),
+  }),
+  async execute(input, ctx) {
+    const partition = resolvePartition(ctx);
+    // The BOUND principal, not the acting one: this is provenance for a record, not a gate. On a
+    // routine fire that resolves to the routine's attested creator, which is the right answer here —
+    // somebody nameable armed the retention, even if not in the room at the time — whereas the
+    // acting principal would be `undefined` and the row would go back to saying "unknown".
+    const armedBy = principalIdOf(ctx);
+    const result = await armCaptureWindow({
+      partition,
+      source: input.source,
+      ...(armedBy !== undefined ? { armedBy } : {}),
+      ...(input.minutes !== undefined ? { windowMs: input.minutes * 60_000 } : {}),
+    });
+    if (!result.ok) return { ok: false, message: result.message };
+    return {
+      ok: true,
+      message:
+        `Recording deliveries to "${input.source}" until ${result.until}, or until ${CAPTURE_MAX_DELIVERIES} have arrived — ` +
+        "whichever comes first. Any previously captured deliveries for this webhook were cleared, so the numbering starts at 1. " +
+        "Run list_recent_events once some have landed.",
+    };
+  },
+  // NO `toModelOutput` — every string this tool returns is host-composed (the handle came from our
+  // own store, the rest is this file's own copy). Nothing an outside party wrote passes through it,
+  // so there is nothing to fence, and fencing host copy would teach the model to discount it.
+});

package/agent/tools/check_pr_status.ts

@@ -0,0 +1,72 @@
+// Read-only GitHub PR status lookup — the primitive the PR-subscription re-arm loop calls on every fire to see what changed since the baseline in its prompt, and useful directly on its own.
+// Mounted on the REPO GRANT: a session whose scope grants no repo cannot name a PR this tool would accept, so it does not see the tool at all. The grant check at execute stays the authoritative wall. The tool needs no APPROVAL at any grain, being a genuine read, so the grant rides a bare `session.started` resolver rather than the window gate.
+// It does pass the ACTING-IDENTITY gate (scm/github-acting-identity.ts), which is a different question: not "may this session read" but "whose account may answer". A read is exactly where that question bites, because the two identities see different repositories.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { resolveAccessFor } from "../access/request.js";
+import { preRegisterDynamicEntry } from "../access/window-gated.js";
+import type { BindableContext } from "../identity/binding.js";
+import { repoAllowed } from "../scm/provider.js";
+import { githubWorkMount } from "../scm/github-work.js";
+import { assertGithubActingIdentity } from "../scm/github-acting-identity.js";
+import { fetchPullRequestStatus, describePrStatus, resolveReadToken } from "../scm/pr-status.js";
+
+// FACTORED, never an inline literal in the resolver body: eve's build transform rewrites an inline
+// `defineTool` inside a `defineDynamic` handler onto a global build-order counter (the hazard
+// scripts/dynamic-tool-replay-test.ts §1 pins). A top-level const stays on the deterministic path.
+export const checkPrStatusEntry = defineTool({
+  description:
+    "Look up the current status of a GitHub pull request — open/closed/merged, draft, title, last updated. Read-only, no approval needed. Use this to check on a PR directly, or to re-check one you're watching via a pr-subscription routine (subscribe_pr).",
+  inputSchema: z.object({
+    repo: z.string().describe("Repository as 'owner/repo'."),
+    number: z.number().int().positive().describe("PR number."),
+  }),
+  outputSchema: z.object({
+    url: z.string(),
+    title: z.string(),
+    state: z.enum(["open", "closed"]),
+    merged: z.boolean(),
+    draft: z.boolean(),
+    updatedAt: z.string(),
+    summary: z.string().describe("One-line human summary — the format the subscription baseline uses."),
+  }),
+  // NO `approval:` — a dynamic-tool approval fn only registers at resolve time, so a resumed
+  // session's replay lookup fails and eve kills the turn (the pin read_notion_page carries).
+  // Read-only, so an absent approval is the same answer `never()` gave.
+  async execute(input, ctx) {
+    const access = resolveAccessFor(ctx);
+    if (!repoAllowed(input.repo, access.repos)) {
+      throw new Error(
+        `repo "${input.repo}" is not granted to this channel. Allowed: ${access.repos.length ? access.repos.join(", ") : "(none)"}. ` +
+          `Grant it via a bundle's repos (see agent/access/bundles.ts).`,
+      );
+    }
+    // 🔴 THE ACTING-IDENTITY GATE RUNS AFTER THE REPO FENCE AND BEFORE THE TOKEN (OPE-1642). The
+    // fence answers "may this session read this repository at all"; the gate answers "whose account
+    // may answer it". Running it first would write a `connector.acting_identity` row for a repository
+    // this session may not name. Running it after `resolveReadToken` would mint an installation token
+    // for a read the gate is about to refuse. The same order `github-read.ts`'s `admitContainer` uses.
+    await assertGithubActingIdentity(ctx as BindableContext, "check_pr_status");
+    const token = await resolveReadToken(input.repo);
+    const status = await fetchPullRequestStatus({ repo: input.repo, number: input.number, token });
+    return {
+      url: status.url,
+      title: status.title,
+      state: status.state,
+      merged: status.merged,
+      draft: status.draft,
+      updatedAt: status.updatedAt,
+      summary: describePrStatus(status),
+    };
+  },
+});
+preRegisterDynamicEntry("check_pr_status", "_single", checkPrStatusEntry);
+
+export default defineDynamic({
+  events: {
+    // `session.started` ONLY: a session's scope cannot change mid-session, so the grant resolves once.
+    // A ROUTINE FIRE resolves it too — the fire's auth bag carries the destination's platform identity attributes, so the fired session binds the routine's real surface and reads the same repo grant the arming turn did. A fire that lost this tool would break a live PR subscription silently.
+    "session.started": (_event, ctx) => (githubWorkMount(ctx as BindableContext) ? checkPrStatusEntry : null),
+  },
+});

package/agent/tools/checkout_repo.ts

@@ -0,0 +1,172 @@
+// Clones one of the GRANTED repos into the sandbox on demand, and fails closed on any repo outside the resolved access bundle. After it, the agent works in the directory with bash and finishes with open_pull_request, which pushes for it.
+// The default read path is firewall-brokered: a READ-ONLY installation token covering the UNION of this session's granted repos is minted HOST-SIDE and injected as a header transform on the git hosts, so the token never enters the sandbox. Only where firewall enforcement genuinely is not available does it fall back to an in-sandbox token, redacted from any error. Not consequential — a read into the workspace with a credential that cannot write — so no approval; the gate is on the PR.
+
+import { defineTool } from "eve/tools";
+import { windowGated } from "../access/window-gated.js";
+import { z } from "zod";
+import { resolveAccessFor } from "../access/request.js";
+import { compileNetworkPolicy } from "../access/egress.js";
+import { resolveHeaders } from "../access/credentials.js";
+import { isEnforced } from "../access/enforcement.js";
+import { narrowByConnectorOverride } from "../access/connector-scope.js";
+import { getConfig } from "../access/config.js";
+import { resolveNetworkAccessLevel } from "../access/network-access.js";
+import { getGitHubApp, repoAllowed } from "../scm/provider.js";
+import { assertGithubActingIdentity } from "../scm/github-acting-identity.js";
+import { githubWorkMount } from "../scm/github-work.js";
+import { READ_PERMISSIONS } from "../scm/mint.js";
+import { mintGitReadBroker, mergeGitReadBroker } from "../scm/broker.js";
+import { auditBrokeredEgressPolicy } from "../scm/broker-audit.js";
+import type { BindableContext } from "../identity/binding.js";
+import { useSelfHostEgress, pushEgressPolicy } from "../access/self-host-egress.js";
+import { checkoutCommand, checkoutCommandBrokered, isSafeCheckoutDir, redactSecret, CHECKOUT_OK, parseConventionProbe, parseSkillsProbe, parseAgentsProbe } from "../scm/git.js";
+import { recordRepoSkills, parseRepoAgent, REPO_SKILL_SEP, type RepoAgentDef } from "../scm/repo-skills.js";
+
+export default windowGated("checkout_repo", defineTool({
+  description:
+    "Clone one of the allowed repositories (see list_repos) into your workspace so you can read and change its code. Only granted repos can be cloned. After it returns, work in the given directory with bash — branch, edit, commit — then call open_pull_request, which pushes your branch and opens the PR after human approval (the checkout credential is read-only; plain `git push` will be rejected). If the result flags a convention file (AGENTS.md or CLAUDE.md), READ it before changing code — it carries the repo's own rules. If the result lists skills or delegation personas shipped in the repo, those become invocable skills from your next turn.",
+  inputSchema: z.object({
+    repo: z.string().describe("owner/repo, exactly as shown by list_repos."),
+    dir: z.string().optional().describe("workspace-relative checkout directory (default: the repo name)."),
+  }),
+  outputSchema: z.object({
+    ok: z.boolean(),
+    dir: z.string(),
+    message: z.string(),
+    // Present only if the repo root has an AGENTS.md/CLAUDE.md — a flag, not the content
+    // (the editor reads it on demand; preloading would pollute the caller's context).
+    conventions: z
+      .object({ file: z.string(), lines: z.number(), bytes: z.number() })
+      .optional(),
+    // Present only if the repo ships skills (.agents/skills/ else .claude/skills/) —
+    // names are the namespaced `<repoSlug>--<skill>` forms the model can invoke.
+    skills: z
+      .object({ count: z.number(), names: z.array(z.string()), truncated: z.boolean() })
+      .optional(),
+    // Present only if the repo ships agent definitions (.agents/agents/ else
+    // .claude/agents/) — surfaced as delegation-persona skills, same namespacing.
+    agents: z
+      .object({ count: z.number(), names: z.array(z.string()), truncated: z.boolean() })
+      .optional(),
+  }),
+  async execute(input, ctx) {
+    const access = resolveAccessFor(ctx);
+    if (!repoAllowed(input.repo, access.repos)) {
+      throw new Error(
+        `repo "${input.repo}" is not granted to this channel. Allowed: ${access.repos.length ? access.repos.join(", ") : "(none)"}. ` +
+          `Grant it via a bundle's repos (see agent/access/bundles.ts).`,
+      );
+    }
+    // The acting-identity gate, after the repo fence and before any credential is resolved — see
+    // check_pr_status.ts for the order. A clone is a READ of repository contents into a sandbox the
+    // model then reads, and the two acting identities reach different repositories, so "clone it
+    // with my own GitHub account" has the same wrong answer here as anywhere else.
+    await assertGithubActingIdentity(ctx as BindableContext, "checkout_repo");
+
+    const app = getGitHubApp();
+    if (!app) {
+      throw new Error("source control isn't configured (no GitHub App). Set OE_GITHUB_APP_* — see .env.example / docs/capabilities/source-control.md.");
+    }
+
+    const dir = input.dir ?? input.repo.split("/")[1];
+    if (!isSafeCheckoutDir(dir)) {
+      throw new Error(`invalid checkout dir "${dir}" — use a simple workspace-relative path.`);
+    }
+    const owner = input.repo.slice(0, input.repo.indexOf("/"));
+    const noInstallationError = () =>
+      new Error(
+        `repo "${input.repo}": its owner has no linked GitHub App installation. ` +
+          `Install the Open Everywhere GitHub App on that org (see docs/capabilities/source-control.md).`,
+      );
+
+    const sandbox = await ctx.getSandbox();
+    let result: Awaited<ReturnType<typeof sandbox.run>>;
+
+    if (isEnforced()) {
+      // Firewall-brokered read, the default: mint the UNION of this session's granted repos rather than just this one, and merge the owner-scoped rule into the STANDING policy — recompiled fresh here rather than reused from cache, so a config change since session start is honoured and the bare github allow is replaced rather than duplicated.
+      // Re-applied on every call to this tool, because these tokens live about an hour, so a per-call re-mint IS the refresh. It threads the same override-narrowing dep and the resolved network-access level the egress hook passes, so a mid-session break-glass revoke or a widened scope is not silently dropped.
+      const basePolicy = await compileNetworkPolicy(
+        access,
+        resolveHeaders,
+        (ids) => narrowByConnectorOverride(ctx, ids),
+        resolveNetworkAccessLevel(access, getConfig().loadNetworkAccess?.() ?? []),
+      );
+      const { rulesByOwner } = await mintGitReadBroker(app, access.repos);
+      if (!rulesByOwner.has(owner)) throw noInstallationError();
+      const brokered = mergeGitReadBroker(basePolicy, rulesByOwner);
+      // Re-apply mid-turn through the SAME channel the session-start hook uses: push the owner-scoped broker policy to the egress proxy where one is wired, otherwise set the sandbox network policy.
+      // Fail-closed: a failed push throws and fails the checkout rather than cloning with an unenforced broker.
+      if (useSelfHostEgress()) {
+        await pushEgressPolicy(brokered);
+      } else {
+        await sandbox.setNetworkPolicy(brokered);
+      }
+      // OPE-1448: the row for the policy just applied. Without it the session's only `egress.policy`
+      // row is the session-start one, whose `writeHosts` names neither git host — so the brokered
+      // write reach on github.com/codeload.github.com existed on no row at all.
+      await auditBrokeredEgressPolicy(ctx as BindableContext, access, brokered, "checkout_repo");
+      result = await sandbox.run({ command: checkoutCommandBrokered(input.repo, dir, app.committer()) });
+      if (!result.stdout.includes(CHECKOUT_OK)) {
+        throw new Error(`clone failed for "${input.repo}": ${(result.stderr || result.stdout || "unknown error").slice(0, 500)}`);
+      }
+    } else {
+      // Firewall enforcement genuinely is not available on this backend or config, so fall back to the in-sandbox token and keep checkout working.
+      // READ-ONLY: this token is persisted into the clone's config, so it must not be able to push — the write token exists only inside the approved PR flow.
+      const { tokens, ungranted } = await app.tokensForRepos([input.repo], READ_PERMISSIONS);
+      if (ungranted.length) throw noInstallationError();
+      const token = tokens.get(owner)!.token;
+      result = await sandbox.run({ command: checkoutCommand(input.repo, token, dir, app.committer()) });
+      if (!result.stdout.includes(CHECKOUT_OK)) {
+        // Redact the token (and its base64 form) from any git output before surfacing it.
+        throw new Error(`clone failed for "${input.repo}": ${redactSecret(result.stderr || result.stdout || "unknown error", token).slice(0, 500)}`);
+      }
+    }
+
+    const conventions = parseConventionProbe(result.stdout) ?? undefined;
+    const conventionNote = conventions
+      ? ` This repo has a ${conventions.file} (${conventions.lines} lines) at ${dir}/${conventions.file} — read it before changing code; it holds the repo's own rules.`
+      : "";
+
+    // Repo-shipped skills and agents are recorded into session state, so the scoped-skills resolver arms them, namespaced, from the next turn.
+    // Fail-soft — a state hiccup must not fail a checkout that already succeeded — and zero discoveries still record, which clears a stale slot from an earlier checkout of the same repo.
+    let skills: { count: number; names: string[]; truncated: boolean } | undefined;
+    let agents: { count: number; names: string[]; truncated: boolean } | undefined;
+    try {
+      const skillsProbe = parseSkillsProbe(result.stdout);
+      const agentsProbe = parseAgentsProbe(result.stdout);
+      const agentDefs: Record<string, RepoAgentDef> = {};
+      for (const [basename, content] of Object.entries(agentsProbe.agents)) {
+        const def = parseRepoAgent(basename, content);
+        agentDefs[def.name] = def;
+      }
+      const slug = recordRepoSkills(input.repo, skillsProbe.skills, agentDefs);
+      if (slug) {
+        const skillNames = Object.keys(skillsProbe.skills).map((name) => `${slug}${REPO_SKILL_SEP}${name}`);
+        if (skillNames.length) skills = { count: skillNames.length, names: skillNames, truncated: skillsProbe.truncated };
+        const agentNames = Object.keys(agentDefs).map((name) => `${slug}${REPO_SKILL_SEP}${name}`);
+        if (agentNames.length) agents = { count: agentNames.length, names: agentNames, truncated: agentsProbe.truncated };
+      }
+    } catch (err) {
+      console.warn(`[open-everywhere:repo-skills] failed to record skills/agents for ${input.repo}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const skillNote = skills
+      ? ` This repo ships ${skills.count} skill(s)${skills.truncated ? " (list truncated)" : ""} — available to you from your next turn as: ${skills.names.join(", ")}.`
+      : "";
+    const agentNote = agents
+      ? ` It also ships ${agents.count} delegation persona(s)${agents.truncated ? " (list truncated)" : ""} — from your next turn, each is a skill that explains how to consult it via the agent tool: ${agents.names.join(", ")}.`
+      : "";
+
+    return {
+      ok: true,
+      dir,
+      conventions,
+      skills,
+      agents,
+      message:
+        `Cloned ${input.repo} into ${dir}/ (authored commits will be ${app.committer().name}). ` +
+        `Branch and commit there, then open_pull_request — it pushes your branch and opens the PR after approval (plain git push is not authorized).${conventionNote}${skillNote}${agentNote}`,
+    };
+  },
+// MOUNT ON THE GRANT (OPE-940), not on the grain alone: a seat whose scope grants no repo cannot
+// clone anything, so it does not see this tool. scm/github-work.ts carries the fail-open reasoning.
+}), githubWorkMount);

package/agent/tools/clear_connector_override.ts

@@ -0,0 +1,159 @@
+// clear_connector_override — PROPOSE reverting an earlier connector revoke back to the
+// config-as-code bundle grants. Same propose/approve mechanics as revoke_connector (see
+// that file's header): this tool posts a confirmation card and returns "awaiting admin
+// approval"; it never clears anything itself. This is a WIDEN-BACK-TO-CONFIG action (it
+// can restore access a revoke had cut), so it goes through the same admin-approval gate
+// as the revoke it undoes — the card is the gate, not a lesser check.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { actingPrincipalId, bindFrom, type SurfaceBinding } from "../identity/binding.js";
+import { principalIdOf, unattendedOf } from "../access/request.js";
+import { resolvePartition } from "../memory/partition.js";
+import { domainForChannel } from "../memory/domain.js";
+import { getConfig } from "../access/config.js";
+import { requestApproval, autoApprovedNote } from "../approvals/flow.js";
+import { checkApprovalVenue, describeVenueRefusal, cardPostedPrefix, cardPostedTail } from "../approvals/card-venue.js";
+import { approvalPostDeps } from "./set_spend_limit.js";
+import { preRegisterDynamicEntry } from "../access/window-gated.js";
+
+export interface ClearConnectorOverrideInput {
+  readonly connector: string;
+  readonly scopeKey?: string;
+}
+
+export interface ConnectorClearPlan {
+  readonly kind: "connector.clear";
+  readonly args: {
+    readonly org: string;
+    readonly scopeKey: string;
+    readonly connector: string;
+  };
+  readonly scopeKey: string;
+  readonly domain: string | null;
+}
+
+/** Pure input -> frozen-args mapping — same card-path / ACTING-sender refusals and
+ *  surface-scoped scopeKey defaulting as planRevokeConnector. No `reason` field: this
+ *  reverts to config, it doesn't introduce a new deviation that needs justifying. */
+export function planClearConnectorOverride(binding: SurfaceBinding, input: ClearConnectorOverrideInput, domain: string | null): ConnectorClearPlan {
+  // NO CARD-PATH REFUSAL HERE ANY MORE (OPE-303) — matching planRevokeConnector, and these two must
+  // move TOGETHER for the same reason they had to widen together: a deployment that can revoke a
+  // connector during an incident but cannot clear the override afterwards has a one-way door, which
+  // is worse than not having the pair at all. Where the card goes is execute()'s venue walk.
+  // principal-gate: presence — this is the only WIDEN verb on the runtime connector lane (the file
+  // header says so: it can restore access a revoke had cut). Everything else about access widens
+  // only through a reviewed PR, so the one runtime exception must not be reachable by a schedule.
+  //
+  // 🔴 THE ACTING principal, never the bound one (OPE-273) — `binding.principalId` was answered by
+  // a fire's attested creator, which is exactly the name that makes a "restore the connector we cut
+  // during the incident" card look like it came from the person who cut it.
+  if (!actingPrincipalId(binding)) {
+    throw new Error("clear_connector_override needs a verified sender on this turn — a triggered routine fire has no acting sender (only the creator it is attributed to), and restoring cut access is a person's decision. Ask someone in this conversation to propose it.");
+  }
+  const connector = input.connector.trim();
+  if (!connector) {
+    throw new Error("clear_connector_override needs a non-empty connector name.");
+  }
+  // The domain-grain default, load-bearing rather than defensive since this tool serves Discord threads too — see planRevokeConnector for the full argument.
+  const scopeKey = input.scopeKey?.trim() || `${binding.platform}/${binding.workspace}/${binding.domainSurface ?? binding.surface}`;
+  return {
+    kind: "connector.clear",
+    args: { org: binding.org, scopeKey, connector },
+    scopeKey,
+    domain,
+  };
+}
+
+// FACTORED + PRE-REGISTERED (access/window-gated.ts's REPLAY DOCTRINE): top-level defineTool const,
+// registered at module load under the deterministic slug-keyed step name, never an inline literal.
+// The surface gate that used to sit on the resolver is gone — see the export at the bottom.
+const clearConnectorOverrideEntry = defineTool({
+  description:
+    "PROPOSE reverting an earlier break-glass connector revoke, restoring this surface's config-as-code bundle grants for that connector — this does NOT clear anything itself. Posts a confirmation card; an org admin, or a domain admin whose domain covers this scope, must click Approve (this widens access back to config, so the admin click is the gate). Use to undo revoke_connector once the incident is resolved. The posted card IS the reply to the user — do not add any narration, summary, or confirmation text after this call; the channel already sees everything the card says. EXCEPT when this surface can't host a card: it then goes to a card-capable channel in the same domain, the `note` field names it, and you MUST relay that.",
+  inputSchema: z.object({
+    connector: z.string().min(1).describe('Connector name to restore, e.g. "notion".'),
+    scopeKey: z
+      .string()
+      .optional()
+      .describe('Override the scope key, e.g. "slack/T123/C456". Defaults to this surface\'s own scope.'),
+  }),
+  outputSchema: z.object({
+    requested: z.boolean(),
+    pendingId: z.string(),
+    expiresAt: z.string().optional().describe("Absent when the chain auto-approved: the row is already decided, so nothing expires."),
+    note: z.string(),
+    autoApproved: z.boolean().optional().describe("The approver chain lowered this verb: no card was posted and it has ALREADY run."),
+  }),
+  // NO `approval:` — an eve DYNAMIC-tool approval fn registers in-process at session.started
+  // resolve time only, so on a RESUMED session in a fresh invocation the replay lookup
+  // fails and eve forces ungrantable "user-approval", killing the turn silently (live
+  // 2026-07-07). Absent approval === never() on both live and replay paths — omit it.
+  async execute(input, ctx) {
+    const binding = bindFrom(ctx);
+    // Approver domain = the TARGET scope's explicit domain (see set_spend_limit.ts for
+    // why) — same domain-grain defaulting expression the plan uses.
+    const scopeKey = input.scopeKey?.trim() || `${binding.platform}/${binding.workspace}/${binding.domainSurface ?? binding.surface}`;
+    const domain = domainForChannel(scopeKey, getConfig().loadDomains())?.name ?? null;
+    const plan = planClearConnectorOverride(binding, input, domain);
+
+    // WHERE THE CARD GOES (OPE-303) — see revoke_connector.ts; the pair resolves it identically.
+    const venueResult = await checkApprovalVenue(binding, resolvePartition(ctx), () => getConfig().loadDomains());
+    if ("refusal" in venueResult) {
+      throw new Error(describeVenueRefusal(venueResult.refusal, binding.platform, "clear that override"));
+    }
+    const venue = venueResult.venue;
+
+    const posted = await requestApproval(
+      {
+        org: plan.args.org,
+        kind: plan.kind,
+        args: plan.args,
+        scopeKey: plan.scopeKey,
+        domain: plan.domain,
+        // The PROVENANCE read on purpose — the card's "asked by" label, guaranteed present by
+        // planClearConnectorOverride's acting-sender refusal above (see set_spend_limit.ts).
+        requestedBy: principalIdOf(ctx)!,
+        channelId: venue.channelId,
+        // Thread the card under the asking conversation (see set_spend_limit.ts) — only when the
+        // card IS in that conversation.
+        threadTs: venue.sameRoom ? binding.threadTs ?? null : null,
+        // Mint-frozen proposing-surface identity (task #105) — the TTL sweep's feedback target,
+        // and the VENUE's key because that is where the card actually is.
+        postedTo: venue.surfaceKey,
+        chain: { unattended: unattendedOf(ctx) },
+      },
+      // The VENUE's own CardPoster — see revoke_connector.ts.
+      approvalPostDeps(venue.platform, ctx),
+    );
+
+    const subject = `clear override for "${plan.args.connector}" on "${plan.args.scopeKey}"`;
+    // Chain-lowered (OPE-296) ⇒ no card, the override is already cleared. See revoke_connector.ts
+    // for why this note stops being internal-only on this branch.
+    if (posted.autoApproved) {
+      return {
+        requested: false,
+        autoApproved: true,
+        pendingId: posted.id,
+        note: autoApprovedNote(subject, posted.autoApproved),
+      };
+    }
+    return {
+      requested: true,
+      pendingId: posted.id,
+      expiresAt: posted.expiresAt,
+      // Internal-only WHEN THE CARD IS HERE (it is then the user-facing reply); on a REDIRECT it is
+      // the only report the asker gets — see revoke_connector.ts.
+      note: `${cardPostedPrefix(venue)} — ${subject} (pending ${posted.id}).` + cardPostedTail(venue, "approve it", posted),
+    };
+  },
+});
+preRegisterDynamicEntry("clear_connector_override", "_single", clearConnectorOverrideEntry);
+
+// MOUNTED EVERYWHERE (OPE-303) — see forget.ts. The dynamic wrapper stays only for
+// preRegisterDynamicEntry's replay-immunity; the surface gate is gone.
+export default defineDynamic({
+  events: {
+    "session.started": () => clearConnectorOverrideEntry,
+  },
+});