autonomous-sdlc-harness 0.2.0 → 0.4.1

package/dist/doctor/checks.js

@@ -21,7 +21,11 @@
  *    that module's {@link GITIGNORE_BLOCK_HEADER}, the line the write engine itself matches on, the
  *    push-settings precedence is `generators/notifications.ts`'s {@link pushEnvCandidates}, the
  *    repository registry's location, reader and staleness grading are `machine/registry.ts`'s {@link registryPath},
- *    {@link readRegistry} and {@link inspect} — the same three `daemon list` enumerates through — and
+ *    {@link readRegistry} and {@link inspect} — the same three `daemon list` enumerates through — the
+ *    remote-execution switch is `config/model.ts`'s {@link remoteExecutionApplies}, the workflow
+ *    paths and the binary run as `gh` are `remote/githubActions.ts`'s ({@link WORKFLOW_RUN_PATH},
+ *    {@link WORKFLOW_RESUME_PATH}, {@link GH_CLI_VARIABLE}, {@link ghCli}), whether a ref carries a
+ *    file is `core/git.ts`'s {@link pathAtRef}, and
  *    the writability probe is the write engine's {@link probeWritable}. A
  *    check that wanted a slightly different answer would be a second definition of the thing being
  *    checked, which is how a green `doctor` starts disagreeing with the run it is supposed to
@@ -54,6 +58,11 @@
  *    did not ask says so, rather than leaving an adopter to read a pass as a promise the packages can
  *    be fetched.
  *
+ *    **Remote setup keeps the same line: it is graded from local evidence by default and asks GitHub
+ *    only under `--check-github`.** {@link REMOTE_EXECUTION_CHECK} reads files, refs and `PATH`, and
+ *    spawns no `gh` subcommand; {@link REMOTE_GITHUB_CHECK} spawns them only under
+ *    {@link CheckContext.probeGithub}, and each is a read.
+ *
  *    **The three docs-retrieval checks keep that line.** `retrieval-dependencies` and
  *    `retrieval-model-cache` are file tests answered by `retrieval/runtime.ts`'s
  *    {@link retrievalRuntimeState} and `retrieval/models.ts`'s {@link modelFilesPresent}, and load
@@ -75,9 +84,10 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, statSyn
 import { delimiter, join, posix, resolve as resolvePath } from 'node:path';
 import { formatProblem } from '../config/check.js';
 import { loadConfig } from '../config/io.js';
-import { answersNone, browserWiringApplies, COMMAND_NONE_SENTINEL, CONFIG_FILENAME, DEFAULTS, FALLBACK_PRESET, isPlaceholder, LAYER_CATCH_ALL_PATH, retrievalApplies, STATE_DIR_DOT_PATTERN, STATE_DIR_PATTERN, } from '../config/model.js';
-import { branchResolves, checkedOutBranch, commitsAhead, configuredRemotes, hasCommits, pathIsIgnored, remoteTrackingBranchResolves, resolveRepoRoot, worktreeList, } from '../core/git.js';
+import { answersNone, browserWiringApplies, COMMAND_NONE_SENTINEL, CONFIG_FILENAME, DEFAULTS, FALLBACK_PRESET, isPlaceholder, LAYER_CATCH_ALL_PATH, remoteExecutionApplies, retrievalApplies, STATE_DIR_DOT_PATTERN, STATE_DIR_PATTERN, } from '../config/model.js';
+import { branchResolves, checkedOutBranch, commitsAhead, configuredRemotes, hasCommits, mainWorktreeRoot, pathAtRef, pathIsIgnored, remoteTrackingBranchResolves, resolveRepoRoot, worktreeList, } from '../core/git.js';
 import { isJsonObject, readJsonFile } from '../core/json.js';
+import { defaultBranchPushCommand, defaultBranchPushReason, WORKFLOW_SCOPE_COMMAND, WORKFLOW_SCOPE_REASON, } from '../core/defaultBranchPush.js';
 import { layerCoverage } from '../core/layerCoverage.js';
 import { layerGapRemedy, recordedVerdictClause } from '../core/layerGapRemedy.js';
 import { nameList } from '../core/nameList.js';
@@ -91,16 +101,17 @@ import { LAYERLESS_BY_DESIGN_PRESETS, SHARED_CONVENTIONS_PATH, TESTS_LAYER_NAME
 import { FORCED_SIGNAL_ID } from '../detect/signals.js';
 import { CLAUDE_MD_PATH, SETUP_PENDING_CLOSE, SETUP_PENDING_OPEN, SKELETON_GUIDANCE_MARKER, TASK_OFFER_PATH, UNFILLED_STUB_MARKER, } from '../generators/claudeContext.js';
 import { caseLabelMatches, isGlobPattern, PRE_PUSH_HOOK, readProtectedCaseLabel, resolveGithooksDir, resolveProtectedBranches, } from '../generators/githooks.js';
-import { PUSH_CMD_KEY, PUSH_URL_KEY, pushEnvCandidates, } from '../generators/notifications.js';
+import { PUSH_CMD_KEY, PUSH_DESTINATION_PLACEHOLDER, PUSH_URL_KEY, pushEnvCandidates, } from '../generators/notifications.js';
 import { DOCS_SEARCH_SERVER_SCRIPT_NAME, outerLoopScriptsDir } from '../generators/outerLoopScripts.js';
-import { bashScriptRule, entryWord, isUnderDirectory, namesBrowserTool, normalizedRoot, pluginRootEntryTarget, PROFILE_PATH, readRule, renderProfile, TEMPLATE_PATH as PROFILE_TEMPLATE_PATH, } from '../generators/permissionProfile.js';
+import { bashScriptRule, entryWord, isUnderDirectory, namesBrowserTool, normalizedRoot, pluginRootDirectories, pluginRootEntries, pluginRootEntryTarget, pluginRootHelpers, PLUGIN_ROOT_ENTRIES_FLAG, PROFILE_PATH, renderProfile, TEMPLATE_PATH as PROFILE_TEMPLATE_PATH, } from '../generators/permissionProfile.js';
 import { ENABLED_PLUGINS_KEY, MARKETPLACE_ENTRY_SHAPE, MARKETPLACE_FLAG, MARKETPLACES_KEY, MARKETPLACE_NAME, marketplaceEntryDefect, PLUGIN_KEY, SETTINGS_PATH, SLUG_SHAPE, } from '../generators/projectSettings.js';
 import { clarificationsIgnoreRules, contentsIgnoredDirectories, GITIGNORE_BLOCK_HEADER, GITIGNORE_PATH, MCP_PATH, } from '../generators/repoRoot.js';
 import { configKeyPath, configuredWrapperFile, scriptInvocation, selectWrapper, wrappedKeyMismatch, wrappedKeyMismatchMessage, WRAPPER_SCRIPTS, wrapperCommandLine, } from '../generators/scripts.js';
 import { selectedStateDirs } from '../generators/stateDir.js';
 import { machineConfigDir } from '../machine/paths.js';
-import { installedPluginsPath, knownMarketplacesPath, pluginHelperPath, pluginHelperScripts, pluginInstallRoot, pluginRuntimeRoot, pluginScriptsDir, } from '../machine/plugins.js';
+import { installedPluginsPath, knownMarketplacesPath, pluginInstallRoot, pluginRuntimeRoot, pluginScriptsDir, } from '../machine/plugins.js';
 import { inspect, readRegistry, registryPath } from '../machine/registry.js';
+import { API_KEY_SECRET, DEFAULT_GH_CLI, GH_CLI_VARIABLE, ghCli, GIT_TOKEN_SECRET, OAUTH_TOKEN_SECRET, PUSH_URL_SECRET, REMOTE_STOP_VARIABLE, runGh, RUNNER_VARIABLE, WORKFLOW_RESUME_FILE, WORKFLOW_RESUME_PATH, WORKFLOW_RUN_FILE, WORKFLOW_RUN_PATH, } from '../remote/githubActions.js';
 import { modelFilesPresent } from '../retrieval/models.js';
 import { retrievalCliEntry, retrievalModelCacheDir, retrievalRuntimeDir, retrievalRuntimeState, } from '../retrieval/runtime.js';
 /**
@@ -123,6 +134,21 @@ const WORKTREE_SCRIPT = 'create-worktree.sh';
  * `bash <scriptsDir>/<file>` — so nothing here formats that shape a second time.
  */
 const REFRESH_SCRIPT = 'refresh-branch.sh';
+/**
+ * The outer-loop script the watcher dispatches a remote run through, named in {@link requiredBinaries}'
+ * and {@link REMOTE_EXECUTION_CHECK}'s sentences on {@link WORKTREE_SCRIPT}'s terms: a file in a
+ * sentence, never resolved or read here.
+ */
+const REMOTE_RUN_SCRIPT = 'remote-run.sh';
+/**
+ * The `gh api` path {@link REMOTE_GITHUB_CHECK} reads the repository's artifact retention from; `gh`
+ * fills `{owner}` and `{repo}` from the checkout's remote. Local, not a `remote/githubActions.ts`
+ * export: that module owns the names `cli/src` shares with the shell and YAML mirrors, and no shell or
+ * YAML file spells this endpoint.
+ */
+const ARTIFACT_RETENTION_ENDPOINT = 'repos/{owner}/{repo}/actions/permissions/artifact-and-log-retention';
+/** Below this many days of artifact retention {@link REMOTE_GITHUB_CHECK} warns; argued there. */
+const ARTIFACT_RETENTION_WARN_DAYS = 30;
 /** The permission lists a generated profile carries, in the order the template writes them. */
 const PERMISSION_LISTS = Object.freeze(['allow', 'deny', 'ask']);
 /** An unsubstituted token, which a raw template's entry may carry and a rendered profile may not. */
@@ -367,11 +393,17 @@ function serversStartedByProfile(profile) {
  * has to report on rather than crash against, and the same holds for a config or a profile that does
  * not parse. Each failure becomes a field the check that owns that subject renders.
  *
- * `probeRegistry` is the caller's answer rather than this function's, and it defaults to `false`: a
- * context built without it is the context every default run gets, and no check here reaches a network
- * unless the command was asked to.
+ * The profile is read from the main checkout ({@link mainWorktreeRoot}, falling back to `repoRoot`
+ * when the probe does not answer), since that is the one a run loads; `repoRoot` stays the checkout
+ * `doctor` runs in, so a linked worktree's profile checks grade the main checkout's file against the
+ * worktree's root.
+ *
+ * `probeRegistry` and `probeGithub` are the caller's answers rather than this function's, and both
+ * default to `false`: a context built without them is the context every default run gets, and no
+ * check here reaches a network unless the command was asked to. `remoteJob` is the caller's too, and
+ * defaults to `false` for the same reason: only the remote job's preflight asks for its grading.
  */
-export function buildCheckContext(cwd, probeRegistry = false) {
+export function buildCheckContext(cwd, probeRegistry = false, probeGithub = false, remoteJob = false) {
     let repoRoot;
     let repoProblem;
     try {
@@ -381,15 +413,19 @@ export function buildCheckContext(cwd, probeRegistry = false) {
         repoProblem = messageOf(error);
     }
     if (repoRoot === undefined)
-        return { cwd, repoProblem, configProblems: [], probeRegistry };
+        return { cwd, repoProblem, configProblems: [], probeRegistry, probeGithub, remoteJob };
     const loaded = loadConfig(repoRoot);
-    const profilePath = join(repoRoot, PROFILE_PATH);
+    const profileRoot = mainWorktreeRoot(repoRoot) ?? repoRoot;
+    const profilePath = join(profileRoot, PROFILE_PATH);
     let profile;
     let profileProblem;
     try {
         const parsed = readJsonFile(profilePath);
         if (parsed === undefined) {
-            profileProblem = `no ${PROFILE_PATH} at ${profilePath}: this repository has no unattended-run permission profile — run \`${CLI} init\` to generate one`;
+            profileProblem =
+                profileRoot === repoRoot
+                    ? `no ${PROFILE_PATH} at ${profilePath}: this repository has no unattended-run permission profile — run \`${CLI} init\` to generate one`
+                    : `no ${PROFILE_PATH} at ${profilePath}: a linked worktree carries no profile of its own, and runs load the main checkout's, at ${profileRoot} — run \`${CLI} init\` there, not in this worktree, to generate one`;
         }
         else if (!isJsonObject(parsed)) {
             profileProblem = `${profilePath} is not a JSON object, so it is not a settings file the agent runner can load`;
@@ -411,6 +447,8 @@ export function buildCheckContext(cwd, probeRegistry = false) {
         profileProblem,
         profilePath,
         probeRegistry,
+        probeGithub,
+        remoteJob,
     };
 }
 /** Is this repository inside a work tree at all — the precondition every repo-wiring check has. */
@@ -1055,7 +1093,7 @@ function deliveryOptInAdvice(candidates) {
     const repositoryRemedy = candidates.some((candidate) => candidate.origin === 'repository')
         ? ', and the repository-side one is filled in by hand'
         : `; this repository configures no repository-side file, so filling one means setting \`pushEnvPath\` in ${CONFIG_FILENAME} first`;
-    return `delivery is opt-in and defaults to nothing pushed, so with neither ${PUSH_URL_KEY} nor ${PUSH_CMD_KEY} set an unattended run's completed, parked and failed events reach a macOS desktop banner where one is available and nothing at all on a Linux host. \`${CLI} init --notifications --push-url <url>\` writes the machine-local file for you${repositoryRemedy}`;
+    return `delivery is opt-in and defaults to nothing pushed, so with neither ${PUSH_URL_KEY} nor ${PUSH_CMD_KEY} set an unattended run's completed, parked and failed events reach a macOS desktop banner where one is available and nothing at all on a Linux host. \`${CLI} init --notifications --push-url ${PUSH_DESTINATION_PLACEHOLDER}\` writes the machine-local file for you${repositoryRemedy}`;
 }
 /**
  * Which settings file an unattended run's notifier will actually read, and whether either delivery
@@ -1597,7 +1635,10 @@ function commandHeads(config, repoRoot) {
  * configuration through and which {@link JQ_CHECK} already treats as a hard floor; and the agent CLI
  * above, whose name arrives as the installed unit's value — `undefined` or empty when the unit does
  * not set it, which is the default case because `${HARNESS_AGENT_CLI:-claude}` reads an empty value
- * as unset too.
+ * as unset too. **A conditional fourth joins them only when {@link remoteExecutionApplies}:** the
+ * binary run as `gh`, which `remote-run.sh` dispatches every remote run through. Its name is the
+ * unit's own {@link GH_CLI_VARIABLE} value when set and non-empty, else {@link DEFAULT_GH_CLI}, on
+ * the agent CLI's terms. With remote execution off the list is exactly the three and the derived.
  *
  * **The unit of comparison is the head of a command line**, over the two places such a line lives, and
  * deriving it is {@link commandHeads}' — this check classifies nothing itself, so it and its sibling
@@ -1623,7 +1664,7 @@ function commandHeads(config, repoRoot) {
  * `ENOENT` in with them printed an unfollowable instruction over the one state `init` clears by
  * itself (Finding 1).
  */
-function requiredBinaries(config, repoRoot, unitAgentCli) {
+function requiredBinaries(config, repoRoot, unitAgentCli, unitGhCli) {
     const found = new Map();
     const ungraded = [];
     // Named `absent` rather than `missing`: in this module a *missing* binary is one the unit's PATH
@@ -1644,6 +1685,10 @@ function requiredBinaries(config, repoRoot, unitAgentCli) {
     add(agent === '' ? DEFAULT_AGENT_CLI : agent, agent === ''
         ? `the watcher's agent binary (${AGENT_CLI_VARIABLE} unset in the unit, so the watcher's default)`
         : `the watcher's agent binary (${AGENT_CLI_VARIABLE}, as the unit sets it)`);
+    if (remoteExecutionApplies(config)) {
+        const gh = unitGhCli?.trim() ?? '';
+        add(gh === '' ? DEFAULT_GH_CLI : gh, `${REMOTE_RUN_SCRIPT}, which the watcher dispatches every run through while execution.target is github-actions (${GH_CLI_VARIABLE} ${gh === '' ? 'unset in the unit, so the default' : 'as the unit sets it'})`);
+    }
     // `deploy` is this check's to skip, on both arms: its command line lives on `deploy.command`
     // rather than in `commands`, and no daemon-launched run deploys. {@link commandHeads} derives it
     // for its other consumer, which does grade it.
@@ -1781,7 +1826,7 @@ const DAEMON_PATH_CHECK = {
             }
             return warn(`the ${backend.kind} unit for ${unit.label} is at ${unit.targetPath} and could not be read (${messageOf(error)}), so the PATH it gives the daemon is unknown: read it yourself, or ${reinstallAdvice(backend.kind)}`);
         }
-        const { binaries: required, ungraded, absent } = requiredBinaries(ctx.config, ctx.repoRoot, unitEnvValue(backend.kind, text, AGENT_CLI_VARIABLE));
+        const { binaries: required, ungraded, absent } = requiredBinaries(ctx.config, ctx.repoRoot, unitEnvValue(backend.kind, text, AGENT_CLI_VARIABLE), unitEnvValue(backend.kind, text, GH_CLI_VARIABLE));
         const envPath = unitEnvValue(backend.kind, text, 'PATH');
         if (envPath === undefined) {
             return warn(`the ${backend.kind} unit for ${unit.label} at ${unit.targetPath} carries no PATH, so the daemon runs on the service manager's own default directories — the state every unit installed before this key shipped is in, and on macOS that is /usr/bin:/bin:/usr/sbin:/sbin, where a Homebrew package manager and an agent CLI under ~/.local/bin both fail to resolve. An unattended run then dies at its first configured command with \`command not found\` while a foreground run is fine, because your shell's PATH is not this. To fix it, ${reinstallAdvice(backend.kind)}`);
@@ -1793,6 +1838,287 @@ const DAEMON_PATH_CHECK = {
         return pass(`the ${backend.kind} unit for ${unit.label} at ${unit.targetPath} carries a PATH reaching every binary an unattended run invokes by name${ungraded.length + absent.length > 0 ? ' that could be derived here' : ''}, each with what requires it: ${nameList(required.map((binary) => `${binary.name} (${binary.sources.join(', ')})`))}. This grades that file rather than this machine — the shell doctor runs in resolves what a service manager's environment does not${describeUngraded(ungraded, absent)}`);
     },
 };
+/**
+ * The configured execution target, and whether this repository has what a remote run needs locally.
+ *
+ * **Remote setup is graded from local evidence by default and asks GitHub only under
+ * `--check-github`** (the module header's choice 3). This reads the two workflow files, one git ref
+ * and `PATH`, and spawns no `gh` subcommand: resolving the binary {@link ghCli} names is the whole of
+ * its `gh` question. What only GitHub can answer — the secrets, the variables, whether GitHub knows
+ * the workflow — the pass text names and leaves to that flag.
+ *
+ * **Every finding is reported, and the grade is the worst of them.** Two `fail`s: no
+ * `harness-run.yml`, because no remote run can be dispatched; and no `gh`, because the watcher
+ * dispatches through it. Three `warn`s: no `harness-resume.yml`, because a usage-paused hosted run then
+ * waits for `/autonomous-sdlc-harness:branch-resume`; a `harness-run.yml` that
+ * `origin/<defaultBranch>` does not carry, because GitHub dispatches only a workflow its default
+ * branch has — the run starts once it is pushed, so nothing is broken here, and its remedy's push
+ * skips the hook because the `pre-push` hook `init` wired refuses every push to the default branch
+ * (`core/defaultBranchPush.ts` owns that push, its `workflow`-scope step and both reasons); and `phases.qa` true,
+ * because a remote run skips the interactive-test phase and the branch still reaches review — the
+ * phase is then owed a local run. It needs no GitHub answer, so it is asked here rather than in
+ * {@link REMOTE_GITHUB_CHECK}.
+ *
+ * `gh` is resolved on **this shell's** `PATH`. Whether the installed daemon's `PATH` reaches it is
+ * {@link DAEMON_PATH_CHECK}'s question, answered there through {@link requiredBinaries}' conditional
+ * member, so it is not asked twice.
+ *
+ * **A missing `origin/<defaultBranch>`, or an unusable `defaultBranch`, leaves the origin row
+ * ungraded** and the detail says so: that ref's absence is {@link REMOTE_CHECK}'s `fail`, and
+ * reporting it again would make one finding two. It is asked only when `harness-run.yml` exists here,
+ * for the same reason. The ref is read as this checkout last fetched it.
+ *
+ * With remote execution off, a workflow file left in place is a `pass` that says it does nothing:
+ * the watcher dispatches nothing while the key is `local`.
+ */
+const REMOTE_EXECUTION_CHECK = {
+    id: 'remote-execution',
+    title: 'the configured execution target, and whether this repository has what a remote run needs locally',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        const root = ctx.repoRoot;
+        const present = (path) => existsSync(join(root, ...path.split('/')));
+        const runPresent = present(WORKFLOW_RUN_PATH);
+        const resumePresent = present(WORKFLOW_RESUME_PATH);
+        if (!remoteExecutionApplies(ctx.config)) {
+            const left = [WORKFLOW_RUN_PATH, WORKFLOW_RESUME_PATH].filter(present);
+            if (left.length === 0)
+                return pass('local execution; remote execution is off (`execution.target`)');
+            return pass(`local execution; remote execution is off (\`execution.target\`), so ${nameList(left)} ${left.length === 1 ? 'is' : 'are'} present and unused: the watcher dispatches nothing while the key is local. \`${CLI} config set execution.target github-actions\` turns remote execution on`);
+        }
+        const failures = [];
+        const warnings = [];
+        const notes = [];
+        if (!runPresent) {
+            failures.push(`${WORKFLOW_RUN_PATH} is absent, so no remote run can be dispatched: re-run \`${CLI} init\`, which writes it create-if-absent while execution.target is github-actions`);
+        }
+        if (!resumePresent) {
+            warnings.push(`${WORKFLOW_RESUME_PATH} is absent, so a hosted run paused on usage waits for /autonomous-sdlc-harness:branch-resume instead of resuming on its own: re-run \`${CLI} init\` to write it`);
+        }
+        const gh = ghCli();
+        if (!resolvesOnPath(gh)) {
+            failures.push(`${gh} does not resolve on this shell's PATH, and the watcher dispatches every remote run through it (${REMOTE_RUN_SCRIPT}): install the GitHub CLI (https://cli.github.com) and run \`gh auth login\`, or point ${GH_CLI_VARIABLE} at it`);
+        }
+        if (ctx.config.phases?.qa === true) {
+            warnings.push("phases.qa is true, but a remote run skips the interactive-test phase — GitHub Actions jobs have no browser wiring, application dependencies or QA credentials for it (docs/remote-execution.md → §3, The interactive-test phase): run /autonomous-sdlc-harness:branch-qa-test <branch> locally before merging a remote run's branch");
+        }
+        if (runPresent) {
+            const branch = ctx.config.defaultBranch;
+            if (typeof branch !== 'string' || branch.trim() === '') {
+                notes.push(`whether GitHub's default branch carries ${WORKFLOW_RUN_PATH} is not graded, because defaultBranch is not a branch name (see the config check)`);
+            }
+            else if (!remoteTrackingBranchResolves(root, branch)) {
+                notes.push(`whether origin/${branch} carries ${WORKFLOW_RUN_PATH} is not graded, because there is no origin/${branch} (see the remote check)`);
+            }
+            else if (!pathAtRef(root, `origin/${branch}`, WORKFLOW_RUN_PATH)) {
+                warnings.push(`origin/${branch} does not carry ${WORKFLOW_RUN_PATH}, as this checkout last fetched it, and GitHub dispatches only a workflow its default branch carries: commit it, then run \`${WORKFLOW_SCOPE_COMMAND}\`, then \`${defaultBranchPushCommand(branch)}\`. ${WORKFLOW_SCOPE_REASON} ${defaultBranchPushReason(branch)}`);
+            }
+        }
+        const noted = notes.length > 0 ? `; ${notes.join('; ')}` : '';
+        const on = 'remote execution is on (execution.target github-actions)';
+        if (failures.length > 0)
+            return fail(`${on}: ${[...failures, ...warnings].join('; ')}${noted}`);
+        if (warnings.length > 0)
+            return warn(`${on}: ${warnings.join('; ')}${noted}`);
+        return pass(`${on}: ${WORKFLOW_RUN_PATH} and ${WORKFLOW_RESUME_PATH} are present and ${gh} resolves on PATH${noted}. What this cannot see lives on GitHub — a credential secret (${OAUTH_TOKEN_SECRET} or ${API_KEY_SECRET}), the ${PUSH_URL_SECRET} and ${GIT_TOKEN_SECRET} secrets, and the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables; \`${CLI} doctor --check-github\` asks GitHub`);
+    },
+};
+/**
+ * What `gh` prints when it cannot reach GitHub at all — `error connecting to api.github.com`, then a
+ * pointer to check the connection. Matched so a network failure grades as *cannot tell* rather than
+ * as the thing asked about being missing.
+ */
+const GH_UNREACHABLE_PATTERN = /error connecting to|check your internet connection/i;
+/**
+ * A stopped call — the bound in `runGh`, or any other signal — and one that could not reach GitHub
+ * are `unknown`; any other non-zero exit is `refused`, quoting `gh`'s own first line.
+ */
+function classifyGh(result) {
+    if (result.status === 0)
+        return { kind: 'answered', stdout: result.stdout };
+    const said = firstLine(result.stderr) || firstLine(result.stdout);
+    if (result.status === null)
+        return { kind: 'unknown', why: 'it was stopped before it answered (timed out)' };
+    if (GH_UNREACHABLE_PATTERN.test(result.stderr))
+        return { kind: 'unknown', why: `it could not reach GitHub (${said})` };
+    return { kind: 'refused', why: said === '' ? `it exited ${result.status}` : `it exited ${result.status}: ${said}` };
+}
+/** The `name` field of each element of a `gh … list --json` array, or `undefined` when it is not that shape. */
+function ghJsonEntries(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed))
+        return undefined;
+    const entries = new Map();
+    for (const item of parsed) {
+        if (!isJsonObject(item) || typeof item.name !== 'string')
+            return undefined;
+        entries.set(item.name, typeof item.value === 'string' ? item.value : '');
+    }
+    return entries;
+}
+/** The positive-integer `days` of an artifact-retention answer, or `undefined` for any other shape. */
+function retentionDaysOf(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isJsonObject(parsed))
+        return undefined;
+    const days = parsed.days;
+    return typeof days === 'number' && Number.isInteger(days) && days > 0 ? days : undefined;
+}
+/**
+ * What GitHub says about the remote setup — asked only under {@link CheckContext.probeGithub}.
+ *
+ * **Off by default** (the module header's choice 3): a default run passes saying it did not ask, and
+ * spawns nothing. Every call goes through `remote/githubActions.ts` → `runGh` with a fixed argument
+ * vector and is a read. Secret **values** are never read: `gh secret list` returns names only.
+ *
+ * Grades, worst wins and every finding is reported:
+ * - `fail` — `gh` does not spawn or `gh auth status` refuses (nothing further is asked); GitHub does
+ *   not know `harness-run.yml`; neither credential secret is set.
+ * - `warn` — `HARNESS_PUSH_URL` absent; `harness-resume.yml` unknown to GitHub; `HARNESS_REMOTE_STOP`
+ *   set; artifact retention below {@link ARTIFACT_RETENTION_WARN_DAYS} days; and any call that timed
+ *   out, could not reach GitHub, or answered in a shape not understood — *cannot tell* is not
+ *   *missing*, so it never fails.
+ * - both credential secrets present is a note, not a finding: billing follows `ANTHROPIC_API_KEY`.
+ * - the retention read refused (typically HTTP 403: the endpoint needs admin access) is a note too —
+ *   the read is best-effort, and a collaborator without admin can still run remotely.
+ *
+ * **Why 30 days.** A parked run waits on a human answer and a usage-paused one on a reset, and the
+ * `harness-state` bundle is the only remote copy of either; once the repository's retention expires
+ * it, the run can no longer be answered and loses its carried counts. Thirty days covers an ordinary
+ * absence — a holiday — while GitHub's own default of 90 passes; below it, an ordinary absence can
+ * cost a parked run its question.
+ */
+const REMOTE_GITHUB_CHECK = {
+    id: 'remote-github',
+    title: 'what GitHub says about the remote setup',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (ctx.config === undefined)
+            return unevaluated(`${CONFIG_FILENAME} could not be read (see the config check)`);
+        if (!remoteExecutionApplies(ctx.config))
+            return pass('remote execution is off (`execution.target`), so nothing was asked of GitHub');
+        if (!ctx.probeGithub)
+            return pass(`not asked — run \`${CLI} doctor --check-github\` to ask GitHub about the secrets, variables and workflows a remote run needs`);
+        const root = ctx.repoRoot;
+        const gh = ghCli();
+        const ask = (args) => {
+            const result = runGh(args, root);
+            return { call: `\`gh ${args.join(' ')}\``, answer: result === undefined ? undefined : classifyGh(result) };
+        };
+        const ghRemedy = `install the GitHub CLI (https://cli.github.com) and run \`gh auth login\`, or point ${GH_CLI_VARIABLE} at it`;
+        const noSpawn = `${gh} could not be run, so GitHub was not asked: ${ghRemedy}`;
+        const cannotTell = (call, why, what) => `cannot tell ${what}: ${call} gave no answer, because ${why}`;
+        const auth = ask(['auth', 'status']);
+        if (auth.answer === undefined)
+            return fail(noSpawn);
+        if (auth.answer.kind === 'unknown')
+            return warn(cannotTell(auth.call, auth.answer.why, 'whether gh is authenticated, so nothing further was asked'));
+        if (auth.answer.kind === 'refused')
+            return fail(`${auth.call} reports no usable login, because ${auth.answer.why}: run \`gh auth login\``);
+        const failures = [];
+        const warnings = [];
+        const notes = [];
+        const run = ask(['workflow', 'view', WORKFLOW_RUN_FILE]);
+        if (run.answer === undefined)
+            return fail(noSpawn);
+        if (run.answer.kind === 'unknown')
+            warnings.push(cannotTell(run.call, run.answer.why, `whether GitHub knows ${WORKFLOW_RUN_FILE}`));
+        if (run.answer.kind === 'refused') {
+            failures.push(`GitHub does not know ${WORKFLOW_RUN_FILE} (${run.call}: ${run.answer.why}), so no remote run can be dispatched: push ${WORKFLOW_RUN_PATH} to the repository's default branch`);
+        }
+        const secrets = ask(['secret', 'list', '--json', 'name']);
+        if (secrets.answer === undefined)
+            return fail(noSpawn);
+        const secretNames = secrets.answer.kind === 'answered' ? ghJsonEntries(secrets.answer.stdout) : undefined;
+        if (secrets.answer.kind !== 'answered') {
+            warnings.push(cannotTell(secrets.call, secrets.answer.why, 'which repository secrets are set'));
+        }
+        else if (secretNames === undefined) {
+            warnings.push(`cannot tell which repository secrets are set: ${secrets.call} answered in a shape this check does not read`);
+        }
+        else {
+            const oauth = secretNames.has(OAUTH_TOKEN_SECRET);
+            const apiKey = secretNames.has(API_KEY_SECRET);
+            if (!oauth && !apiKey) {
+                failures.push(`neither ${OAUTH_TOKEN_SECRET} nor ${API_KEY_SECRET} is a repository secret, so a remote run cannot authenticate its agent: set one with \`gh secret set <name>\` — billing follows ${API_KEY_SECRET} when both are set`);
+            }
+            else if (oauth && apiKey) {
+                notes.push(`both ${OAUTH_TOKEN_SECRET} and ${API_KEY_SECRET} are set, so billing follows ${API_KEY_SECRET}`);
+            }
+            if (!secretNames.has(PUSH_URL_SECRET)) {
+                warnings.push(`${PUSH_URL_SECRET} is not a repository secret, so notifications from a remote run reach no one: set it with \`gh secret set ${PUSH_URL_SECRET}\``);
+            }
+        }
+        const resume = ask(['workflow', 'view', WORKFLOW_RESUME_FILE]);
+        if (resume.answer === undefined)
+            return fail(noSpawn);
+        if (resume.answer.kind === 'unknown')
+            warnings.push(cannotTell(resume.call, resume.answer.why, `whether GitHub knows ${WORKFLOW_RESUME_FILE}`));
+        if (resume.answer.kind === 'refused') {
+            warnings.push(`GitHub does not know ${WORKFLOW_RESUME_FILE} (${resume.call}: ${resume.answer.why}), so usage auto-resume is unavailable: push ${WORKFLOW_RESUME_PATH} to the repository's default branch`);
+        }
+        const variables = ask(['variable', 'list', '--json', 'name,value']);
+        if (variables.answer === undefined)
+            return fail(noSpawn);
+        const variableValues = variables.answer.kind === 'answered' ? ghJsonEntries(variables.answer.stdout) : undefined;
+        let runner;
+        if (variables.answer.kind !== 'answered') {
+            warnings.push(cannotTell(variables.call, variables.answer.why, `the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables`));
+        }
+        else if (variableValues === undefined) {
+            warnings.push(`cannot tell the ${RUNNER_VARIABLE} and ${REMOTE_STOP_VARIABLE} variables: ${variables.call} answered in a shape this check does not read`);
+        }
+        else {
+            const label = variableValues.get(RUNNER_VARIABLE)?.trim() ?? '';
+            runner = label === '' ? 'GitHub-hosted (`ubuntu-latest`)' : `runner label \`${label}\``;
+            if ((variableValues.get(REMOTE_STOP_VARIABLE) ?? '') !== '') {
+                warnings.push(`${REMOTE_STOP_VARIABLE} is set, so every remote start and continuation is stopped: \`gh variable delete ${REMOTE_STOP_VARIABLE}\` lifts it`);
+            }
+        }
+        const retention = ask(['api', ARTIFACT_RETENTION_ENDPOINT]);
+        if (retention.answer === undefined)
+            return fail(noSpawn);
+        let retentionDays;
+        if (retention.answer.kind === 'unknown') {
+            warnings.push(cannotTell(retention.call, retention.answer.why, 'how long the repository keeps artifacts'));
+        }
+        else if (retention.answer.kind === 'refused') {
+            notes.push(`artifact retention not checked: ${retention.call} needs admin access (${retention.answer.why})`);
+        }
+        else {
+            retentionDays = retentionDaysOf(retention.answer.stdout);
+            if (retentionDays === undefined) {
+                warnings.push(`cannot tell how long the repository keeps artifacts: ${retention.call} answered in a shape this check does not read`);
+            }
+            else if (retentionDays < ARTIFACT_RETENTION_WARN_DAYS) {
+                warnings.push(`the repository keeps artifacts for ${retentionDays} days, so a remote run parked or paused longer than that loses its state bundle: raise it under Settings → Actions → General → Artifact and log retention`);
+            }
+        }
+        const noted = notes.length > 0 ? `; ${notes.join('; ')}` : '';
+        if (failures.length > 0)
+            return fail(`${[...failures, ...warnings].join('; ')}${noted}`);
+        if (warnings.length > 0)
+            return warn(`${warnings.join('; ')}${noted}`);
+        const kept = retentionDays === undefined ? '' : `, and the repository keeps artifacts for ${retentionDays} days`;
+        return pass(`gh is authenticated, GitHub knows ${WORKFLOW_RUN_FILE} and ${WORKFLOW_RESUME_FILE}, a credential secret and ${PUSH_URL_SECRET} are set, and remote runs use ${runner}${kept}${noted}`);
+    },
+};
 /**
  * The config's shape, re-checked at runtime.
  *
@@ -2891,7 +3217,10 @@ const PLUGIN_WIRING_CHECK = {
         return pass(`${SETTINGS_PATH} enables ${PLUGIN_KEY} and declares the ${MARKETPLACE_NAME} marketplace in the shape the agent runner reads, so a clone of this repository resolves the plugin from the committed file`);
     },
 };
-/** Is there a permission profile, and does it parse? Everything below reads it. */
+/**
+ * Is there a permission profile, and does it parse? Everything below reads it. In a linked worktree it
+ * grades the main checkout's profile, the one a run loads ({@link buildCheckContext}).
+ */
 const PROFILE_CHECK = {
     id: 'permission-profile',
     title: `${PROFILE_PATH} exists and parses`,
@@ -2903,6 +3232,27 @@ const PROFILE_CHECK = {
         return pass(`${ctx.profilePath} parses as the settings document an unattended run loads`);
     },
 };
+/**
+ * The route that stops a committed profile from reaching a remote job: untrack it on the default
+ * branch, so the job's create-if-absent `init` finds none and generates its own.
+ *
+ * The commit must land on the **default branch**, because every run's branch is cut from
+ * `origin/<defaultBranch>` (`create-worktree.sh` → `worktree add … "origin/$default_branch"`): an
+ * untrack pushed only to a run branch covers that one run, and the next branch carries the profile
+ * again. The push and its `--no-verify` reason are `core/defaultBranchPush.ts`'s, spelled nowhere here.
+ *
+ * Called by {@link PROFILE_PATHS_CHECK} under `--remote-job`, and by {@link PROFILE_TRACKED_CHECK}.
+ */
+function profileUntrackRemedy(ctx) {
+    const configured = ctx.config?.defaultBranch;
+    const branch = typeof configured === 'string' && configured !== '' ? configured : '<defaultBranch>';
+    const commands = [
+        `git rm --cached ${PROFILE_PATH}`,
+        'git commit -m "Stop tracking the machine-local permission profile"',
+        defaultBranchPushCommand(branch),
+    ];
+    return `${commands.map((command) => `\`${command}\``).join(', then ')}. The commit must land on ${branch}, because every run's branch is cut from origin/${branch}, so an untrack pushed only to a run branch covers that one run and the next branch carries the profile again. ${defaultBranchPushReason(branch)}`;
+}
 /**
  * Do the profile's absolute paths still name this checkout?
  *
@@ -2911,6 +3261,11 @@ const PROFILE_CHECK = {
  * at a location that no longer exists. A `warn`, because the fix is a re-run rather than an edit and
  * because a hand-tuned profile is a file the adopter may deliberately have pointed elsewhere.
  *
+ * **A `fail` under `--remote-job`** ({@link CheckContext.remoteJob}): there the profile was committed
+ * from another machine and the job's create-if-absent `init` kept it, so the job cannot regenerate it
+ * — the step that runs `init` refuses a rewrite of a tracked file, which is why `init --force` is not
+ * printed there. The remedy is {@link profileUntrackRemedy}, so the job generates its own.
+ *
  * The question asked is "does any rule cover this root", not "is every path correct": a profile
  * generated here mentions the root in its edit, write and read rules, so its complete absence is the
  * signal.
@@ -2918,10 +3273,11 @@ const PROFILE_CHECK = {
  * "Cover" is deliberately not "contain" ({@link namesRoot}). A generated profile names two locations —
  * the checkout it was generated at, and the sibling-worktree pattern that is emitted unconditionally
  * beside it — and a sibling worktree is covered by the second while appearing in neither as a
- * substring. Warning there would be a standing false alarm in exactly the checkouts the flow runs in,
- * and its remediation is the damaging part: an `init --force` inside a worktree regenerates the
- * **committed** profile with that worktree as `<repo_root>`, leaving the main checkout named by
- * nothing, since `<work>/<project>` does not match `<work>/<project>-*`.
+ * substring. A linked worktree carries no profile of its own — the profile is gitignored and
+ * machine-local — so in a worktree this check grades the main checkout's profile, the one the watcher
+ * loads, against the worktree's root, which the sibling-worktree glob covers. A false warning there
+ * would send the operator to `init --force` inside the worktree, which writes a profile naming the
+ * worktree that no run ever loads.
  */
 const PROFILE_PATHS_CHECK = {
     id: 'profile-paths',
@@ -2932,11 +3288,39 @@ const PROFILE_PATHS_CHECK = {
         if (ctx.profile === undefined)
             return unevaluated(`${PROFILE_PATH} could not be read (see the permission-profile check)`);
         const covered = locationStrings(ctx.profile).some((entry) => namesRoot(entry, ctx.repoRoot));
+        if (!covered && ctx.remoteJob) {
+            return fail(`neither a path nor a pattern in ${PROFILE_PATH} covers this repository root (${ctx.repoRoot}): the profile was generated on another machine and committed, and this job's create-if-absent \`${CLI} init\` kept it, so a run loading it would find its edit, write, read and script rules matching nothing here. Stop tracking it so the job generates its own: ${profileUntrackRemedy(ctx)}`);
+        }
         return covered
             ? pass(`the profile's rules cover this repository root (${ctx.repoRoot}) — by naming it, or by a pattern such as the sibling-worktree glob that matches it — so they apply to this checkout`)
             : warn(`neither a path nor a pattern in ${PROFILE_PATH} covers this repository root (${ctx.repoRoot}): the profile was generated for another location, so a run loading it would find its edit, write, read and script rules matching nothing here — re-run \`${CLI} init --force\` from the checkout the profile should be generated for, which writes a .bak sibling before regenerating it`);
     },
 };
+/**
+ * Is the permission profile carried by the tree `HEAD` names?
+ *
+ * `pass` when it is not; `warn` when it is; **`fail` under `--remote-job`** ({@link CheckContext.remoteJob}).
+ * A committed profile reaches every clone and every job, and a job cannot replace it: its
+ * create-if-absent `init` keeps a present file, and the step that runs `init` refuses a rewrite of a
+ * tracked one. On a person's machine the committed file may still name this checkout, so nothing stops
+ * yet. Both non-pass grades print {@link profileUntrackRemedy}, the one route that works in both places.
+ *
+ * Asks about `ctx.repoRoot`, the checkout `doctor` runs in, not the main checkout the profile is read
+ * from in a linked worktree: what is committed is a property of the tree, not of where it is loaded.
+ */
+const PROFILE_TRACKED_CHECK = {
+    id: 'profile-tracked',
+    title: 'the permission profile is machine-local, not committed',
+    run: (ctx) => {
+        if (ctx.repoRoot === undefined)
+            return unevaluated('the repository root did not resolve (see the git check)');
+        if (!pathAtRef(ctx.repoRoot, 'HEAD', PROFILE_PATH)) {
+            return pass(`${PROFILE_PATH} is not in the tree HEAD names, so no clone and no remote job receives this machine's copy; each generates its own`);
+        }
+        const finding = `${PROFILE_PATH} is committed at HEAD: it carries this machine's absolute paths, and a remote job keeps a committed one rather than generating its own. Stop tracking it: ${profileUntrackRemedy(ctx)}`;
+        return ctx.remoteJob ? fail(finding) : warn(finding);
+    },
+};
 /**
  * The closure that must **not** be in a generated profile: no `deny` entry may name a browser tool.
  *
@@ -3034,26 +3418,38 @@ function namesHelperScript(entry) {
  *   because those scripts are the interactive-test phase's alone. With the phase off this check says
  *   nothing whatever about them: a warning nobody with that phase off can act on is one they learn
  *   to skip.
- * - A `Read` rule at a runtime root that differs from the install root, **not** phase-gated:
- *   instruction files and samples are read by every unattended run, interactive-test phase or not.
- * - **No `Read` rule over the install root**, and the asymmetry is a measurement rather than a
- *   taste. Measured 2026-08-26, under a generated profile naming no rule over either root: sixteen
- *   `Read` calls under the install root succeeded, over eight distinct instruction files, while ten
- *   under the runtime root were refused in the same run.
- *
- * With nothing left to grade — the phase off at a single root — it reports **not graded** and names
- * which, rather than a pass an adopter would read as coverage.
- *
- * The helper names come from **reading `<root>/scripts/`** ({@link pluginHelperScripts}) at each
+ * - A `Read` rule at the **runtime root**, including where it is also the install root, **not**
+ *   phase-gated: instruction files and samples are read by every unattended run, interactive-test
+ *   phase or not. So every resolved root set carries at least one required entry.
+ * - **No `Read` rule over an install root distinct from the runtime root**, and the asymmetry is a
+ *   measurement rather than a taste. Measured 2026-08-26 on a `directory`-sourced marketplace, under
+ *   a generated profile naming no rule over either root: sixteen `Read` calls under the install root
+ *   — a cache snapshot the runtime does not substitute — succeeded, over eight distinct instruction
+ *   files, while ten under the runtime root were refused in the same run. Observed 2026-09-28 in
+ *   Gate 12 round 1, on a GitHub-hosted runner with a GitHub-sourced marketplace, where one root is
+ *   both: every `Read` of `<root>/instructions/*.md` asked for permission, and `cat`/`ls` were
+ *   refused as outside "the allowed working directory". An install root that is also the runtime
+ *   root is therefore not exempt.
+ *
+ * The helper names come from **reading `<root>/scripts/`** ({@link pluginRootHelpers}) at each
  * graded root and taking the union, never from a list kept here: they are declared once, in the
  * plugin's own `scripts/README.md`, and a copy in this file would be a second declaration that
  * drifts the first time one is added. Nothing here classifies a helper by its call site either —
  * the root set is what varies, and the name set stays read from disk.
  *
- * **It never fails**, for {@link REPO_REGISTRY_CHECK}'s reason: this is a machine-local gap with an
- * operator remedy, and the profile is a file the adopter owns. And when no root resolves it invents
- * none — it names the step and the file it read, because a fabricated path is worse than no path: an
- * operator would paste it and get a profile that is wrong in a way nothing reports.
+ * **It never fails outside `--remote-job`**, for {@link REPO_REGISTRY_CHECK}'s reason: this is a
+ * machine-local gap with an operator remedy, and the profile is a file the adopter owns. And when no
+ * root resolves it invents none — it names the step and the file it read, because a fabricated path is
+ * worse than no path: an operator would paste it and get a profile that is wrong in a way nothing
+ * reports.
+ *
+ * **Under `--remote-job`** ({@link CheckContext.remoteJob}) a missing entry and an unresolved root are
+ * each a `fail`, and every directory {@link pluginRootDirectories} returns for the graded roots is
+ * required in `permissions.additionalDirectories` — the shell-readable grant. The job differs because
+ * the plugin was installed and the profile generated moments earlier on a machine that exists for one
+ * run, so a gap is a launch that parks rather than an operator's paste. Outside the flag that list is
+ * not graded: a missing shell grant has not been observed to stall a run on a person's machine, and a
+ * version-carrying directory would go stale at every upgrade.
  *
  * **A helper entry under no resolved root is named in every *graded* disposition and moves no
  * grade.** A profile carrying dead weight and every required entry still passes; one missing a
@@ -3077,8 +3473,8 @@ const PLUGIN_PERMISSIONS_CHECK = {
             return unevaluated('the repository root did not resolve (see the git check)');
         if (ctx.profile === undefined)
             return unevaluated(`${PROFILE_PATH} could not be read (see the permission-profile check)`);
-        // Read here rather than beside `missing` below, because both the not-graded and the no-root
-        // dispositions return above that point and each interpolates a count out of it. A pure read of
+        // Read here rather than beside `missing` below, because the no-root disposition returns above
+        // that point and interpolates a count out of it. A pure read of
         // the profile: it neither writes nor throws on a malformed one, and `missing` is still computed
         // from it where it always was.
         const allowed = permissionEntries(ctx.profile, 'allow');
@@ -3104,6 +3500,9 @@ const PLUGIN_PERMISSIONS_CHECK = {
             const dangling = ungraded === 0
                 ? ''
                 : `. ${PROFILE_PATH} carries ${ungraded} absolute-directory \`permissions.allow\` ${entryWord(ungraded)} outside this checkout that nothing here can grade until a root resolves, counted rather than named because calling one stale or required would be a judgement no record on this machine supports; \`${CLI} init --force\` carries ${ungraded === 1 ? 'it' : 'them'} forward unverified in the meantime`;
+            if (ctx.remoteJob) {
+                return fail(`${installedPluginsPath()} records no install root for ${PLUGIN_KEY}, so the entries ${PROFILE_PATH} needs for it cannot be named and are not guessed at: a remote job installs the plugin before this preflight, so no record means that install did not take effect on this runner — a run launched now would be refused every read of the plugin's instruction files${dangling}`);
+            }
             return warn(`${installedPluginsPath()} records no install root for ${PLUGIN_KEY}, so the entries ${PROFILE_PATH} needs for it cannot be named and are not guessed at: enable the plugin — open this repository with the agent runner once, which applies the ${SETTINGS_PATH} keys \`${CLI} init\` wrote — and re-run \`${CLI} doctor\`, which reads the root back and prints the exact lines to paste${dangling}`);
         }
         // Entries in the helper form whose directory no root here answers for. Two exclusions, both
@@ -3118,7 +3517,7 @@ const PLUGIN_PERMISSIONS_CHECK = {
                 return [];
             return resolvedRoots.some((root) => isUnderDirectory(target, root)) ? [] : [`${entry} — ${target}`];
         });
-        // Carried into all three surviving dispositions, so what the report says about dead weight does
+        // Carried into both surviving dispositions, so what the report says about dead weight does
         // not depend on which arm this machine happens to be in. Empty set, empty clause — as `partial`.
         const stray = strays.length === 0
             ? ''
@@ -3129,7 +3528,7 @@ const PLUGIN_PERMISSIONS_CHECK = {
         // complete that is one unreadable file away from a stall.
         const phaseKnown = ctx.config !== undefined;
         const qaOn = ctx.config?.phases?.qa === true;
-        const helpers = qaOn ? [...new Set(roots.flatMap((root) => pluginHelperScripts(root)))].sort() : [];
+        const helpers = pluginRootHelpers(roots, qaOn);
         const groups = roots.map((root) => ({
             root,
             label: split
@@ -3139,57 +3538,58 @@ const PLUGIN_PERMISSIONS_CHECK = {
                 : installRoot === undefined
                     ? `the directory this marketplace is sourced from (the only root that resolved: ${installedPluginsPath()} records no install root)`
                     : `the one plugin root this machine resolves, recorded in ${installedPluginsPath()}`,
-            required: [
-                // Outside the phase gate, and only where the runtime root is its own directory: reads at the
-                // install root were measured to succeed ungranted, ten at the runtime root to be refused.
-                ...(root === installRoot
-                    ? []
-                    : [{ rule: readRule(root), symptom: 'improvises in place of a contract file it is refused' }]),
-                ...helpers.map((name) => ({
-                    rule: bashScriptRule(pluginHelperPath(root, name)),
-                    symptom: 'parks with no error at the first helper script it reaches',
-                })),
-            ],
+            // The builder `init --plugin-root-entries` writes through too, so the two cannot differ. The
+            // read rule is outside the phase gate and required at the runtime root, including where it is
+            // also the install root; only an install root distinct from it is exempt.
+            required: pluginRootEntries(root, { isRuntimeRoot: root === runtimeRoot, helpers }).map(({ kind, rule }) => ({
+                rule,
+                symptom: kind === 'read'
+                    ? 'improvises in place of a contract file it is refused'
+                    : 'parks with no error at the first helper script it reaches',
+            })),
         }));
         const required = groups.flatMap((group) => group.required);
-        if (required.length === 0) {
-            const reason = !phaseKnown
-                ? `${CONFIG_FILENAME} could not be read, so the phase the helper scripts belong to is unknown (see the config check)`
-                : qaOn
-                    ? `no helper script was found under ${pluginScriptsDir(firstRoot)}: a plugin root with no scripts directory is a broken or partial install, and re-enabling the plugin is what repairs it`
-                    : "phases.qa is off, and the helper scripts are that phase's alone";
-            return pass(`not graded at this machine's plugin root (${firstRoot}), because ${reason}.${stray}`);
-        }
-        // Two graded roots and no helper name under either is still a broken install, and the read rule
-        // alone would otherwise let it pass in silence once pasted.
-        const partial = qaOn && helpers.length === 0
-            ? ' No helper script was found under any graded root, so none is required here: that is a broken or partial install, which re-enabling the plugin repairs.'
-            : '';
+        // A root that resolves always carries the runtime root's `Read`, so `required` is never empty
+        // here; what the helper entries could not be graded against is said on both dispositions.
+        const partial = !phaseKnown
+            ? ` ${CONFIG_FILENAME} could not be read, so the phase the helper scripts belong to is unknown and no helper entry was graded (see the config check).`
+            : qaOn && helpers.length === 0
+                ? ` No helper script was found under ${split ? 'any graded root' : pluginScriptsDir(firstRoot)}, so none is required here: that is a broken or partial install, which re-enabling the plugin repairs.`
+                : '';
         // Stated once, in both dispositions, because an operator reading either has to know why a line
-        // they already pasted at one root reappears at the other, and why only one root carries a read
-        // rule. `coincide` is the ordinary machine: one directory, one set of entries, no read rule.
-        const coincide = !split && installRoot !== undefined;
+        // they already pasted at one root reappears at the other, and which root carries a read rule.
         const why = (split
             ? ` Both roots are graded because a helper named in an instruction file is resolved by the agent itself while one named in an agent definition body has \`\${CLAUDE_PLUGIN_ROOT}\` substituted by the runtime, and on this machine those two routes were measured to land on different directories.`
             : '') +
-            (coincide
-                ? ''
-                : ` The \`Read\` entry is graded at the runtime root and not at the install root because reads at the install root were measured (2026-08-26) to succeed under a profile naming no rule over it, while ten at the runtime root were refused in that same run; it is outside the \`phases.qa\` gate, because instruction files and samples are read by every run.`);
+            ` The \`Read\` entry is required at the runtime root, including where it is also the install root, and outside the \`phases.qa\` gate, because instruction files and samples are read by every run: on 2026-09-28 a GitHub-hosted runner whose one plugin root was both was refused every \`Read\` of its instruction files under a profile naming no rule over it. It is not required at an install root distinct from the runtime root${split ? ', as here' : ''}: reads there were measured (2026-08-26, a \`directory\`-sourced marketplace) to succeed under a profile naming no rule over it, while ten at the runtime root were refused in that same run.`;
         const missing = required.filter((entry) => !allowed.includes(entry.rule));
+        // Graded under `--remote-job` only, through the same pure read `allowed` came from.
+        const granted = permissionEntries(ctx.profile, 'additionalDirectories').map(normalizedRoot);
+        const missingDirectories = ctx.remoteJob
+            ? pluginRootDirectories(roots).filter((directory) => !granted.includes(directory))
+            : [];
+        const directoryBlock = missingDirectories.length === 0 ? '' : `\n\npermissions.additionalDirectories:\n${missingDirectories.join('\n')}`;
+        const jobClause = ctx.remoteJob
+            ? ' Under --remote-job this is a failure: the plugin was installed and the profile generated moments earlier on a machine that exists for one run, so a gap here is a launch that parks rather than an operator\'s paste.'
+            : '';
+        const jobRemedy = ` In a remote job \`${CLI} init ${PLUGIN_ROOT_ENTRIES_FLAG}\`, which the job's setup step runs, writes these into the profile it generates, so a profile lacking them is one that step did not generate — a committed copy its create-if-absent run kept, which the profile-tracked check names the untrack route for — or one whose plugin root carries a character the permission guard matches literally, which that step warned about in its own log. The lines below are what is missing:`;
+        if (missing.length === 0 && missingDirectories.length > 0) {
+            return fail(`${PROFILE_PATH} carries every \`permissions.allow\` entry this machine's plugin ${split ? 'roots need' : 'root needs'}, but its \`permissions.additionalDirectories\` lacks ${missingDirectories.length === 1 ? 'the plugin root' : `${missingDirectories.length} plugin roots`}, so a shell command in a run is refused a read under ${missingDirectories.length === 1 ? 'it' : 'them'} as outside the allowed working directory.${jobClause}${stray}${jobRemedy}${directoryBlock}`);
+        }
         if (missing.length > 0) {
             const symptoms = [...new Set(missing.map((entry) => entry.symptom))].join(', and ');
             const blocks = groups
                 .map((group) => ({ group, rules: group.required.filter((entry) => missing.includes(entry)).map((entry) => entry.rule) }))
                 .filter(({ rules }) => rules.length > 0)
                 .map(({ group, rules }) => renderRootGroup(group.label, group.root, rules));
-            return warn(`${PROFILE_PATH} is missing ${missing.length} of the ${required.length} \`permissions.allow\` ${entryWord(required.length)} this machine's plugin ${split ? 'roots need' : 'root needs'}, so an unattended run ${symptoms}. \`${CLI} init\` does not generate ${missing.length === 1 ? 'it' : 'them'} — a root is machine-local and the install root carries the plugin version, so an entry written once goes stale on an upgrade and this check re-derives ${split ? 'both' : 'it'} instead.${why}${partial}${stray} Add each line below to that list as its own string, unquoted exactly as it stands:\n${blocks.join('\n\n')}`);
+            return (ctx.remoteJob ? fail : warn)(`${PROFILE_PATH} is missing ${missing.length} of the ${required.length} \`permissions.allow\` ${entryWord(required.length)} this machine's plugin ${split ? 'roots need' : 'root needs'}, so an unattended run ${symptoms}.${ctx.remoteJob ? '' : ` \`${CLI} init\` does not generate ${missing.length === 1 ? 'it' : 'them'} — a root is machine-local and the install root carries the plugin version, so an entry written once goes stale on an upgrade and this check re-derives ${split ? 'both' : 'it'} instead.`}${why}${partial}${jobClause}${stray}${ctx.remoteJob ? jobRemedy : ` Add each line below to ${directoryBlock === '' ? 'that list' : 'that list, or to `permissions.additionalDirectories` under its own heading,'} as its own string, unquoted exactly as it stands:`}\n${blocks.join('\n\n')}${directoryBlock}`);
         }
         // Per-root counts only where there is more than one root to attribute them to; with a single
         // root the leading total already says how many, and repeating it reads as a second figure.
         const carried = groups
             .map((group) => split ? `${group.label} — ${group.root}: ${group.required.length} ${entryWord(group.required.length)}` : `${group.label} — ${group.root}`)
             .join('; ');
-        return pass(`${PROFILE_PATH} carries all ${required.length} \`permissions.allow\` ${entryWord(required.length)} this machine's plugin ${split ? 'roots need' : 'root needs'} — ${carried}.${why}${partial}${stray}${coincide ? ` \`${readRule(firstRoot)}\` is deliberately not one of them — measured 2026-08-26, reads under that root succeed under a profile carrying no rule naming it.` : ''}`);
+        return pass(`${PROFILE_PATH} carries all ${required.length} \`permissions.allow\` ${entryWord(required.length)} this machine's plugin ${split ? 'roots need' : 'root needs'} — ${carried}.${ctx.remoteJob ? ` Under --remote-job its \`permissions.additionalDirectories\` was graded too, and carries every plugin root, so a shell command in a run may read under ${split ? 'them' : 'it'}.` : ''}${why}${partial}${stray}`);
     },
 };
 /**
@@ -3583,6 +3983,12 @@ const RETRIEVAL_INDEX_CHECK = {
  * for the machine around it — and they are meant to be read together. `daemon-path` comes last of
  * the six because it is the only one that grades an *installed* unit: it has nothing to say until the
  * five above it are answered, and it says so rather than guessing.
+ * `remote-execution` follows it because it asks the same "can this run unattended" question of a run
+ * the watcher dispatches to GitHub rather than spawns here, and `remote-github` follows that because it
+ * asks GitHub the half of the same question local evidence cannot answer.
+ *
+ * `profile-tracked` sits under `profile-paths` because the two name the same file carried somewhere it
+ * does not belong, and a committed profile is the usual reason a job's `profile-paths` fails.
  *
  * `plugin-permissions` closes the profile block for the same shape of reason: it is the only profile
  * question whose other half is not in the repository at all — the plugin's machine-local install
@@ -3608,6 +4014,8 @@ export const CHECKS = Object.freeze([
     REPO_REGISTRY_CHECK,
     MACHINE_FOOTPRINT_CHECK,
     DAEMON_PATH_CHECK,
+    REMOTE_EXECUTION_CHECK,
+    REMOTE_GITHUB_CHECK,
     CONFIG_CHECK,
     COMMAND_WRAPPERS_CHECK,
     COMMAND_PERMISSIONS_CHECK,
@@ -3622,6 +4030,7 @@ export const CHECKS = Object.freeze([
     PLUGIN_WIRING_CHECK,
     PROFILE_CHECK,
     PROFILE_PATHS_CHECK,
+    PROFILE_TRACKED_CHECK,
     PROFILE_BROWSER_DENY_CHECK,
     PROFILE_DENY_FLOOR_CHECK,
     PLUGIN_PERMISSIONS_CHECK,