autonomous-sdlc-harness 0.2.0 → 0.4.0

package/dist/generators/notifications.js

@@ -12,10 +12,10 @@
  * declares exactly {@link PUSH_URL_KEY} and {@link PUSH_CMD_KEY}. The credential-bearing value is
  * therefore the push **URL**, and its home is the machine-local `push.env` that `docs/watcher.md`
  * §6 already names as the first file the notifier reads. "Guided ntfy setup" ships accordingly as a
- * vendor-neutral endpoint prompt whose guided line uses `https://ntfy.sh/<your-topic>` as the
- * worked example rather than as the only thing that works.
+ * vendor-neutral destination: an adopter may give an ntfy topic name, which is written as its
+ * `https://ntfy.sh/<topic>` address, or the full URL of any endpoint that accepts a POST.
  *
- * ## Three non-obvious choices, and where each comes from
+ * ## Four non-obvious choices, and where each comes from
  *
  * 1. **An opt-in with no endpoint writes nothing — and that is the whole point of the file.**
  *    `docs/watcher.md` §6's precedence is that the machine-local file wins and the repository's
@@ -24,17 +24,32 @@
  *    file that already has values, turning an opt-in into a silent opt-out. When the answer to
  *    "where should notifications be posted" is nothing, this generator enqueues nothing and returns
  *    the guided setup as a note instead.
- * 2. **The value is never logged back.** The run's action log names the path the write engine
- *    wrote, the note names the two keys, and neither says what the URL is — the same discipline
+ * 2. **The value is never logged back — a topic name no more than a URL.** The run's action log
+ *    names the path the write engine wrote, the note names the two keys and which form was
+ *    recognised, and none of them says what the URL or the topic is — the same discipline
  *    `autonomous-notify.sh`'s header states for the delivery side ("NO VALUE IS EVER PRINTED, by
  *    this script or in a failure line — only paths and key names"). A push URL is a bearer
- *    credential for every endpoint worth pointing this at, and a terminal scrollback is not where
- *    it belongs.
+ *    credential for every endpoint worth pointing this at, and an ntfy topic is one too: the public
+ *    server has no account behind a topic, so anyone who knows its name can read and post to it. An
+ *    answer that is neither form is not repeated either, because it is most likely a mistyped one.
+ *    A terminal scrollback is not where any of them belongs.
  * 3. **The precedence has exactly one definition on the TypeScript side**, {@link pushEnvCandidates},
  *    so a `doctor` check reporting which file is in effect reads that order rather than re-joining
  *    either path. Two derivations of a first-wins order is two answers to the one question anybody
  *    asks about these files, and the answers would differ exactly where it matters — on a machine
  *    that has both.
+ * 4. **One grammar for the destination, and a file that survives being sourced.**
+ *    {@link resolvePushDestination} is the only definition of what may be given, and
+ *    {@link PUSH_DESTINATION_FORMS} the only sentence describing it, for the reason choice 3 gives
+ *    for the precedence; {@link UNRECOGNISED_DESTINATION_NOTE}, the line `init`'s re-ask prints,
+ *    is produced here too. The file is a shell fragment `autonomous-notify.sh` sources under
+ *    `set -a`, so {@link pushEnvContent} single-quotes a URL outside a conservative character set:
+ *    an unquoted `&` or `;` in a query string would break the file or run a command. The grammar
+ *    refuses `'`, so single quotes always suffice.
+ *
+ * **Finding: `autonomous-notify.sh` needs no change for the topic form.** The stored value is
+ * always a full URL, which it POSTs verbatim; a topic is resolved to its address here, before the
+ * file is written.
  *
  * Nothing here touches the filesystem: the generator plans, and `init` applies the plan once — so
  * `--dry-run` writes no machine-local file for the same structural reason it writes nothing inside
@@ -52,13 +67,68 @@ export const PUSH_CMD_KEY = 'HARNESS_PUSH_CMD';
 /** Mode of the written file: it holds a credential, so it is the owner's to read and nobody else's. */
 const PUSH_ENV_MODE = 0o600;
 /**
- * The worked example in the guided setup — an endpoint that accepts a POST and needs no account.
+ * A value bash reads back unchanged when written unquoted in an assignment. `~` is deliberately
+ * outside it: bash tilde-expands it after a `:` in an assignment.
+ */
+const SHELL_SAFE_VALUE = /^[A-Za-z0-9._:/?#@%+=,-]+$/;
+/** The public ntfy server a bare topic name is posted to. */
+export const NTFY_PUBLIC_ORIGIN = 'https://ntfy.sh';
+/** The ntfy server's own topic-name rule; a name outside it is one the server would refuse. */
+const NTFY_TOPIC_PATTERN = /^[-_A-Za-z0-9]{1,64}$/;
+/** The one placeholder every flag row, note and advice line prints for the destination. */
+export const PUSH_DESTINATION_PLACEHOLDER = '<url-or-ntfy-topic>';
+/**
+ * What an ntfy topic becomes once written. Module-private: it reaches callers only inside
+ * {@link PUSH_DESTINATION_FORMS}, which is the surface every caller quotes.
+ */
+const GUIDED_ENDPOINT_EXAMPLE = `${NTFY_PUBLIC_ORIGIN}/<your-topic>`;
+/**
+ * The one description of what may be given as a push destination: a noun phrase, without a final
+ * stop, so a caller can write "Type {@link PUSH_DESTINATION_FORMS}." or "takes …; the value given is
+ * neither". Every surface asking for or refusing a destination interpolates it rather than
+ * re-wording it.
+ */
+export const PUSH_DESTINATION_FORMS = `either an ntfy topic name — install the free ntfy app from the App Store or Play Store, create a topic there and type its name, with no server and no account needed (it is posted to as ${GUIDED_ENDPOINT_EXAMPLE}); the name works like a password, because anyone who knows it can read and send these notifications, so choose one nobody would guess — or the full http:// or https:// URL of any other endpoint that accepts a POST`;
+const NOT_REPEATED_CLAUSE = 'it is not repeated here, because a push destination is a credential';
+/**
+ * The line `init`'s re-ask prints after an unrecognised answer. It names no form, because the
+ * question it follows interpolates {@link PUSH_DESTINATION_FORMS}, and never quotes the answer.
+ */
+export const UNRECOGNISED_DESTINATION_NOTE = `That answer is not one of the forms asked for, so it was not used; ${NOT_REPEATED_CLAUSE}.`;
+const HTTP_SCHEME = /^https?:\/\//i;
+// `'` is refused so the single-quoting in `pushEnvContent` can never be broken out of.
+const UNWRITABLE_IN_URL = /[\s\u0000-\u001f\u007f']/;
+const NTFY_HOSTED_TOPIC = /^ntfy\.sh\/([^/]*)\/?$/i;
+/**
+ * Resolve a push destination as given — a full `http://` / `https://` URL, `ntfy.sh/<topic>`, or a
+ * bare ntfy topic name — to the URL the notifier posts to.
  *
- * Exported so `init`'s prompt and this generator's guided note quote **one** example: two would be
- * two answers to "what does a URL that works look like", and the prompt is where the question is
- * first asked while the note is where an unanswered one is explained.
+ * **The rule this function exists to enforce: it is the only grammar for this value, and every
+ * entry point calls it** — the `--push-url` flag, the terminal prompt, {@link writeNotifications},
+ * and any later one such as `ROADMAP.md`'s unshipped `notifications set-url`. A second copy of the
+ * grammar is two answers to "what may I type here".
+ *
+ * A URL is kept as typed (trimmed), not normalised through `URL.href`, so what is written is what
+ * the adopter gave.
  */
-export const GUIDED_ENDPOINT_EXAMPLE = 'https://ntfy.sh/<your-topic>';
+export function resolvePushDestination(answer) {
+    const trimmed = answer.trim();
+    if (HTTP_SCHEME.test(trimmed) && !UNWRITABLE_IN_URL.test(trimmed)) {
+        let hostname = '';
+        try {
+            hostname = new URL(trimmed).hostname;
+        }
+        catch {
+            hostname = '';
+        }
+        if (hostname !== '')
+            return { kind: 'url', url: trimmed };
+    }
+    const topic = NTFY_HOSTED_TOPIC.exec(trimmed)?.[1] ?? trimmed;
+    if (NTFY_TOPIC_PATTERN.test(topic))
+        return { kind: 'ntfy-topic', url: `${NTFY_PUBLIC_ORIGIN}/${topic}` };
+    return { kind: 'unrecognised' };
+}
 /** The machine-local push-notification settings file — the first file the notifier reads. */
 export function machinePushEnvPath() {
     return join(machineConfigDir(), PUSH_ENV_FILENAME);
@@ -111,8 +181,12 @@ function repositoryPushEnvPath(repoRoot, config) {
  * copy is. Nor does it restate what either key does: that is `autonomous-notify.sh`'s header, which
  * is the one implementation of the delivery arms, and a second account of it here would be the copy
  * that goes stale.
+ *
+ * The value is written unquoted only inside {@link SHELL_SAFE_VALUE}, and single-quoted otherwise
+ * (module header, choice 4).
  */
 function pushEnvContent(url) {
+    const value = SHELL_SAFE_VALUE.test(url) ? url : `'${url}'`;
     return [
         '# Push notifications for unattended runs — machine-local, written by',
         '# `npx autonomous-sdlc-harness init --notifications`.',
@@ -126,8 +200,12 @@ function pushEnvContent(url) {
         '# It holds a credential: it is created 0600 inside a 0700 directory, it is outside every',
         '# repository so it cannot be committed by accident, and no command in this CLI prints a value',
         '# from it back. Edit it freely — `init` creates it once and a later run leaves it as you left it.',
+        '#',
+        `# ${PUSH_URL_KEY} always holds a full URL: an ntfy topic is written as ${NTFY_PUBLIC_ORIGIN}/<topic>,`,
+        '# and the topic name in it is itself the credential — anyone who knows it can read and post to it.',
+        "# The file is sourced by a shell, so a URL containing `&`, `;` or a space must stay single-quoted.",
         '',
-        `${PUSH_URL_KEY}=${url}`,
+        `${PUSH_URL_KEY}=${value}`,
         `${PUSH_CMD_KEY}=`,
         '',
     ].join('\n');
@@ -135,14 +213,16 @@ function pushEnvContent(url) {
 /**
  * Enqueue the machine-local settings file, or explain why nothing was written.
  *
- * Three outcomes, and the middle one is the one to read first:
+ * Four outcomes, and the second is the one to read first:
  *
  * - **opt-in not taken** — nothing is enqueued and a note records that delivery stays opt-in and
  *   defaults to nothing pushed, which is what every release before this one did;
  * - **opt-in taken with no endpoint** — nothing is enqueued, and the note carries the guided setup:
  *   the path, the two key names and a worked example. Writing an empty file here would shadow a
  *   repository-side file that already has values (choice 1 in the module header);
- * - **opt-in taken with an endpoint** — the directory at `0700` and the file at `0600`, both
+ * - **opt-in taken with a destination {@link resolvePushDestination} does not recognise** — nothing
+ *   is enqueued, for the same reason, and one warning says so without repeating the value;
+ * - **opt-in taken with a recognised destination** — its resolved URL is written; the directory at `0700` and the file at `0600`, both
  *   `allowOutsideRepo`, the file `create-if-absent` so a re-run leaves an edited one alone.
  */
 export function writeNotifications({ repoRoot, config, plan, enabled, pushUrl, }) {
@@ -163,13 +243,19 @@ export function writeNotifications({ repoRoot, config, plan, enabled, pushUrl, }
         if (pushUrl !== undefined) {
             warnings.push('--push-url was given without --notifications, so it was not written anywhere: the endpoint is only ever written into the machine-local push-notification settings file, and that file is written only when the opt-in is taken — re-run with --notifications to take it and set the endpoint in the same run');
         }
-        notes.push(`no push-notification settings were written and none were changed: delivery is opt-in and defaults to nothing pushed, so an unattended run's completed, parked and failed events reach a desktop banner where one is available and nothing else. Re-run with --notifications --push-url <url> to write ${target}, or ${repositoryRemedy} — the machine-local file is read first and the repository one only when it is absent (docs/watcher.md §6)`);
+        notes.push(`no push-notification settings were written and none were changed: delivery is opt-in and defaults to nothing pushed, so an unattended run's completed, parked and failed events reach a desktop banner where one is available and nothing else. Re-run with --notifications --push-url ${PUSH_DESTINATION_PLACEHOLDER}, giving ${PUSH_DESTINATION_FORMS}, to write ${target}, or ${repositoryRemedy} — the machine-local file is read first and the repository one only when it is absent (docs/watcher.md §6)`);
         return { written: false, notes, warnings };
     }
     if (pushUrl === undefined) {
-        notes.push(`push notifications were asked for and no endpoint was given, so nothing was written — deliberately: the machine-local file is read before ${repositoryName} and while it exists that one is not read at all, so an empty ${target} would shadow values you may already have there and turn this opt-in into a silent opt-out. Re-run with --push-url <url>, naming any endpoint that accepts a POST (${GUIDED_ENDPOINT_EXAMPLE} is the worked example: choose a topic name nobody would guess, subscribe to it in an ntfy client, and that URL is the endpoint), or write ${target} yourself with ${PUSH_URL_KEY} set and ${PUSH_CMD_KEY} empty`);
+        notes.push(`push notifications were asked for and no destination was given, so nothing was written — deliberately: the machine-local file is read before ${repositoryName} and while it exists that one is not read at all, so an empty ${target} would shadow values you may already have there and turn this opt-in into a silent opt-out. Re-run with --push-url ${PUSH_DESTINATION_PLACEHOLDER}, giving ${PUSH_DESTINATION_FORMS}; or write ${target} yourself with ${PUSH_URL_KEY} set to a full URL and ${PUSH_CMD_KEY} empty`);
+        return { written: false, notes, warnings };
+    }
+    const destination = resolvePushDestination(pushUrl);
+    if (destination.kind === 'unrecognised') {
+        warnings.push(`the push destination given is not ${PUSH_DESTINATION_FORMS}, so nothing was written; ${NOT_REPEATED_CLAUSE}. Re-run with --notifications --push-url ${PUSH_DESTINATION_PLACEHOLDER}, or write ${target} yourself with ${PUSH_URL_KEY} set to a full URL and ${PUSH_CMD_KEY} empty`);
         return { written: false, notes, warnings };
     }
+    const recognised = destination.kind === 'ntfy-topic' ? `the ntfy topic you gave, as its ${NTFY_PUBLIC_ORIGIN} address` : 'the URL you gave';
     plan.add({
         path: machineConfigDir(),
         policy: 'ensure-dir',
@@ -180,12 +266,12 @@ export function writeNotifications({ repoRoot, config, plan, enabled, pushUrl, }
     plan.add({
         path: target,
         policy: 'create-if-absent',
-        content: pushEnvContent(pushUrl),
+        content: pushEnvContent(destination.url),
         label: 'machine-local push-notification settings',
         mode: PUSH_ENV_MODE,
         allowOutsideRepo: true,
     });
-    notes.push(`${target} is the machine-local push-notification settings file, written to hold ${PUSH_URL_KEY} and an empty ${PUSH_CMD_KEY} — the endpoint itself is deliberately not printed here or anywhere else. It is machine-local rather than committed, and it is read before ${repositoryName}, which is then not read at all. It is create-if-absent: a file already there is kept exactly as you edited it and still carries the endpoint it was written with, so --push-url on a re-run sets nothing — to point it elsewhere, edit ${PUSH_URL_KEY} in it by hand, or re-run with --force, which copies it to a .bak sibling and re-writes it from this run's --push-url`);
+    notes.push(`${target} is the machine-local push-notification settings file, written to hold ${PUSH_URL_KEY}, set to ${recognised}, and an empty ${PUSH_CMD_KEY} — the endpoint itself is deliberately not printed here or anywhere else. It is machine-local rather than committed, and it is read before ${repositoryName}, which is then not read at all. It is create-if-absent: a file already there is kept exactly as you edited it and still carries the endpoint it was written with, so --push-url on a re-run sets nothing — to point it elsewhere, edit ${PUSH_URL_KEY} in it by hand, or re-run with --force, which copies it to a .bak sibling and re-writes it from this run's --push-url`);
     return { written: true, notes, warnings };
 }
 //# sourceMappingURL=notifications.js.map

package/dist/generators/notifications.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/generators/notifications.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/generators/notifications.ts"],"names":[],"mappings":"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"}

package/dist/generators/outerLoopScripts.js

@@ -1,6 +1,8 @@
 /**
- * Generator: the outer-loop scripts — the run watcher, the git wrappers, the worktree tooling and
- * the shared library they all source — written into the adopter's configured `scriptsDir`.
+ * Generator: the outer-loop scripts — the run watcher, the git wrappers, the worktree tooling, the
+ * flow walker with its gate library and flow graph, the test-suite runner, and the shared library
+ * they all source —
+ * written into the adopter's configured `scriptsDir`.
  *
  * **The rule this module exists to enforce: {@link OUTER_LOOP_SCRIPTS} is the single declaration of
  * which outer-loop files ship, where each one lands, what mode it carries and which of them an
@@ -68,7 +70,8 @@ export const NOTIFY_SCRIPT_NAME = 'autonomous-notify.sh';
 export const DOCS_SEARCH_SERVER_SCRIPT_NAME = 'docs-search-server.sh';
 /**
  * The whole outer-loop set, in the order `init` writes it: the shared library first, because every
- * other row sources it.
+ * other row sources it, and each further library or data file before the script that sources or
+ * reads it.
  *
  * **Declared once, here.** One row is one line, and adding a script is adding its template plus its
  * row — no condition threaded through the writer, no second list to keep in step.
@@ -85,6 +88,14 @@ export const OUTER_LOOP_SCRIPTS = Object.freeze([
     // regenerated, which is the whole point of shipping it as a script rather than as an interpreter
     // allow entry.
     Object.freeze({ file: 'scratch-run.sh', mode: 0o755, agentInvocable: true }),
+    // Sourced and read by `flow-walker.sh` from its own directory, never run.
+    Object.freeze({ file: 'flow-walker-gates.sh', subdir: 'lib', mode: 0o644, agentInvocable: false }),
+    Object.freeze({ file: 'task_plan_writing.graph.json', subdir: 'flows', mode: 0o644, agentInvocable: false }),
+    // Run by the orchestrating session; no `DENY_SCRIPT_BASENAMES` entry, because it must be reachable.
+    Object.freeze({ file: 'flow-walker.sh', mode: 0o755, agentInvocable: true }),
+    // Run by the orchestrating session in the Run gates phase; no `DENY_SCRIPT_BASENAMES` entry,
+    // because it must be reachable.
+    Object.freeze({ file: 'run-test-suite.sh', mode: 0o755, agentInvocable: true }),
     Object.freeze({ file: 'create-worktree.sh', mode: 0o755, agentInvocable: false }),
     Object.freeze({ file: 'setup-worktree.sh', mode: 0o755, agentInvocable: false }),
     // Started by the agent runner from `.mcp.json`, never by a dispatched agent's Bash call, so `false`
@@ -96,6 +107,9 @@ export const OUTER_LOOP_SCRIPTS = Object.freeze([
     Object.freeze({ file: NOTIFY_SCRIPT_NAME, mode: 0o755, agentInvocable: false }),
     Object.freeze({ file: WATCHER_SCRIPT_NAME, mode: 0o755, agentInvocable: false }),
     Object.freeze({ file: 'restart-watcher.sh', mode: 0o755, agentInvocable: false }),
+    // Run by the watcher, the remote job or a person. Carries a `DENY_SCRIPT_BASENAMES` entry: a run that
+    // could dispatch runs could start runs about itself.
+    Object.freeze({ file: 'remote-run.sh', mode: 0o755, agentInvocable: false }),
 ]);
 /** The templates' subdirectory under `cli/templates/`, addressed as {@link readTemplate} wants it. */
 const TEMPLATE_DIR = 'scripts';

package/dist/generators/outerLoopScripts.js.map

@@ -1 +1 @@
-{"version":3,"file":"outerLoopScripts.js","sourceRoot":"","sources":["../../src/generators/outerLoopScripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAsB,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA+ChD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,uBAAuB,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAmC,MAAM,CAAC,MAAM,CAAC;IAC9E,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAChG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IACjF,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAC5E,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAC/E,kGAAkG;IAClG,8FAA8F;IAC9F,mGAAmG;IACnG,+FAA+F;IAC/F,iGAAiG;IACjG,eAAe;IACf,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAC5E,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACjF,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAChF,oGAAoG;IACpG,6FAA6F;IAC7F,uBAAuB;IACvB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,8BAA8B,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAC3F,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAC1F,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAC1F,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAC/E,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAChF,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;CACzE,CAAC,CAAC;AAEZ,sGAAsG;AACtG,MAAM,YAAY,GAAG,SAAS,CAAC;AAqC/B;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAuB;IAC3D,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,OAAO,gBAAgB,CAAC,MAAM,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,MAAqB,EAAE,YAAoB;IAC/F,OAAO,IAAI,CAAC,QAAQ,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAA2B;IACvF,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;IAE5G,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAC1B,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC;gBACP,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC;gBACxC,MAAM,EAAE,YAAY;gBACpB,KAAK,EAAE,gCAAgC,MAAM,EAAE;aAChD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC;YACP,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxD,MAAM,EAAE,kBAAkB;YAC1B,OAAO,EAAE,YAAY,CAAC,GAAG,YAAY,IAAI,QAAQ,EAAE,CAAC;YACpD,KAAK,EAAE,qBAAqB,QAAQ,EAAE;YACtC,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,gBAAgB,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,KAAK,GACT,OAAO,CAAC,MAAM,KAAK,CAAC;QAClB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC;YACE,GAAG,OAAO,CAAC,MAAM,eAAe,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,cAAc,iBAAiB,UAAU,4RAA4R;SAC5Y,CAAC;IAER,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"outerLoopScripts.js","sourceRoot":"","sources":["../../src/generators/outerLoopScripts.ts"],"names":[],"mappings":"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"}

package/dist/generators/permissionProfile.js

@@ -92,7 +92,8 @@
  * ## What this module deliberately does not do
  *
  * - **It touches no filesystem beyond reading its two templates — and, on a forced run, the profile
- *   it is about to replace.** {@link writePermissionProfile} enqueues the rendered profile into the
+ *   it is about to replace; under `init --plugin-root-entries`, the agent runner's plugin records.**
+ *   {@link writePermissionProfile} enqueues the rendered profile into the
  *   command's write plan under the `create-if-absent` contract — the profile is hand-tuned after
  *   generation, and an overwrite silently drops the allow entries an adopter added to close a stall —
  *   and the write itself belongs to the write engine. `--force` is the one flag that suspends that
@@ -103,7 +104,14 @@
  *   outside this checkout, unverified: a run that graded nothing revokes nothing. That is a read and
  *   not a question put to the adopter again: they
  *   were told once, by `doctor`, exactly which lines to paste. Preserving an entry is not generating
- *   one — the open owner decision below is untouched by it.
+ *   one: by default nothing here generates one, and the once-open owner decision below is taken for
+ *   the opt-in `init --plugin-root-entries` only, the default unchanged. Under that switch
+ *   {@link generatedPluginRootEntries} reads the plugin records through {@link resolvedPluginRoots}
+ *   on every run, forced or not, and still never tests whether the profile exists: whether the render
+ *   lands is the write engine's `create-if-absent` answer, which `init` hands back to
+ *   {@link pluginRootEntriesNote}. On a forced run the generated lines are appended before the
+ *   carry-forward, which skips any line already in `allow`, so each line has one producer — the rule
+ *   the browser-fragment section states.
  * - **It adds no `hooks` key.** The plugin ships its own guard hooks, which fire from the plugin,
  *   resolve their own root and append to the adopter's hooks rather than replacing them; writing
  *   them into user settings as well would run each guard twice. The template says so in a comment
@@ -126,9 +134,11 @@
  *   `plugin-permissions` check re-derives the root on every run and prints each missing line — and
  *   {@link QA_TEMPLATE_PATH}'s `_README` carries the entry *form* an adopter adds by hand, which the
  *   `create-if-absent` contract above — and, on the run that suspends it, the carry-forward named
- *   there — is what makes survive every later `init`. Whether `init`
- *   should also *write* those entries is an open owner decision rather than a closed one; nothing
- *   here takes it. Moving the helpers somewhere a rule can name unconditionally — the adopter's own
+ *   there — is what makes survive every later `init`. Whether `init` should also *write* those
+ *   entries was an open owner decision, now taken for `--plugin-root-entries` only, default unchanged:
+ *   inside a remote job the plugin is installed immediately before `init` runs and the profile dies
+ *   with the job, so neither reason above holds there, while both still hold for the default.
+ *   Moving the helpers somewhere a rule can name unconditionally — the adopter's own
  *   `scriptsDir`, which the three wrapper forms already reach — would remove the manual step but
  *   change the invocation form everywhere the shipped instruction corpus calls them, so it belongs
  *   to the item that ships them (`plugin/scripts/README.md`) and not to this module.
@@ -183,7 +193,7 @@ import { isJsonObject, readJsonFile } from '../core/json.js';
 import { defaultProjectName, readTemplate, workRoot as resolveWorkRoot, worktreeGlob } from '../core/paths.js';
 import { normalizeRepoDir } from '../core/repoPaths.js';
 import { containsToken, renderTemplate } from '../core/templating.js';
-import { installedPluginsPath, pluginInstallRoot, pluginRuntimeRoot, SCRIPTS_DIRNAME } from '../machine/plugins.js';
+import { installedPluginsPath, pluginHelperPath, pluginHelperScripts, pluginInstallRoot, pluginRuntimeRoot, SCRIPTS_DIRNAME, } from '../machine/plugins.js';
 import { SEARCH_TOOL_PERMISSION } from '../retrieval/server.js';
 import { OUTER_LOOP_SCRIPTS, outerLoopRelativePath, } from './outerLoopScripts.js';
 import { scriptInvocation, selectWrapper, WRAPPER_SCRIPTS, wrapperInvocation, } from './scripts.js';
@@ -565,16 +575,16 @@ function entriesOf(permissions, list) {
  *
  * It is also one of the two forms a **plugin-root** entry is written in: `doctor`'s
  * `plugin-permissions` check prints those lines for an operator to paste, and
- * {@link pluginRootEntryTarget} reads one back. Nothing in this generator emits one for a plugin
- * root — the module header's standing decision.
+ * {@link pluginRootEntryTarget} reads one back. This generator emits one for a plugin root only
+ * under `init --plugin-root-entries`, through {@link pluginRootEntries} — the module header's decision.
  */
 export function readRule(absolutePath) {
     return `Read(/${absolutePath}/**)`;
 }
 /**
  * A wrapper-script rule, in the unquoted `Bash(bash <path>:*)` form every generated one uses — and
- * the other plugin-root form, for a helper under the plugin's own scripts directory. Same two
- * consumers, and the same standing decision, as {@link readRule}.
+ * the other plugin-root form, for a helper under the plugin's own scripts directory. Same consumers,
+ * and the same decision, as {@link readRule}.
  */
 export function bashScriptRule(absolutePath) {
     return `Bash(${INVOCATION_PREFIX}${absolutePath}:*)`;
@@ -942,6 +952,63 @@ function resolvedPluginRoots(repoRoot) {
     const roots = [pluginRuntimeRoot(repoRoot), pluginInstallRoot(repoRoot)];
     return [...new Set(roots.filter((root) => root !== undefined).map(normalizedRoot))];
 }
+/**
+ * The helper-script names graded at every root: the sorted, de-duplicated union of
+ * {@link pluginHelperScripts} over `roots` while `phases.qa` is on, and empty while it is off — the
+ * helpers are that phase's alone. Called by `doctor`'s `plugin-permissions` check and by
+ * {@link generatedPluginRootEntries}, so the two cannot grade different names.
+ */
+export function pluginRootHelpers(roots, qaOn) {
+    return qaOn ? [...new Set(roots.flatMap((root) => pluginHelperScripts(root)))].sort() : [];
+}
+/**
+ * The entries one root requires: {@link readRule} unless it is the install root — reads there were
+ * measured to succeed ungranted (`doctor/checks.ts`, `PLUGIN_PERMISSIONS_CHECK`) — then
+ * {@link bashScriptRule} for each of `helpers`, in that order. The one per-root builder, called by
+ * that check and by {@link generatedPluginRootEntries}.
+ */
+export function pluginRootEntries(root, options) {
+    return [
+        ...(options.isInstallRoot ? [] : [{ kind: 'read', rule: readRule(root) }]),
+        ...options.helpers.map((name) => ({ kind: 'helper', rule: bashScriptRule(pluginHelperPath(root, name)) })),
+    ];
+}
+/** The switch as a message names it — and as `init`'s option row spells it. */
+export const PLUGIN_ROOT_ENTRIES_FLAG = '--plugin-root-entries';
+/**
+ * The entries `doctor`'s `plugin-permissions` check requires at every root {@link resolvedPluginRoots}
+ * returns, built by the same two functions it calls, or `undefined` when no root resolves. An entry
+ * a root path would make unmatchable is warned about and left out rather than handed to
+ * {@link assertRunnable}, which would bill a machine-local path to this CLI.
+ */
+function generatedPluginRootEntries(repoRoot, config, warn) {
+    const roots = resolvedPluginRoots(repoRoot);
+    if (roots.length === 0)
+        return undefined;
+    const installRoot = pluginInstallRoot(repoRoot);
+    const install = installRoot === undefined ? undefined : normalizedRoot(installRoot);
+    const helpers = pluginRootHelpers(roots, config.phases?.qa === true);
+    return roots
+        .flatMap((root) => pluginRootEntries(root, { isInstallRoot: root === install, helpers }))
+        .map(({ rule }) => rule)
+        .filter((rule) => {
+        const forbidden = FORBIDDEN_IN_ENTRY.find(([needle]) => rule.includes(needle));
+        if (forbidden === undefined)
+            return true;
+        warn(`${PLUGIN_ROOT_ENTRIES_FLAG} left out ${JSON.stringify(rule)}: the plugin root it names contains ${forbidden[1]}, which the permission guard matches literally, so the entry would match nothing at run time`);
+        return false;
+    });
+}
+/**
+ * The note `init` reports for `--plugin-root-entries` once the plan is applied: the kept-profile line
+ * when `effect` is `'kept'` and entries were appended; undefined otherwise. `effect` is the write
+ * engine's answer for {@link PROFILE_PATH}, identical under `--dry-run`, so the line is too.
+ */
+export function pluginRootEntriesNote(outcome, effect) {
+    if (outcome !== 'appended' || effect !== 'kept')
+        return undefined;
+    return `${PLUGIN_ROOT_ENTRIES_FLAG} had no effect: ${PROFILE_PATH} already exists and is kept under its create-if-absent contract, so the plugin-root entries this run rendered do not reach it. Run \`${DOCTOR_COMMAND}\` for the lines it lacks, or \`init --force ${PLUGIN_ROOT_ENTRIES_FLAG}\` to regenerate it after a .bak`;
+}
 /**
  * The `permissions.allow` entries of the profile currently on disk, or **an empty list for every way
  * that can fail** — absent, unreadable, not JSON, not an object, no `permissions`, no `allow`.
@@ -1099,7 +1166,7 @@ function appendCarriedPluginRootEntries(profile, { repoRoot, dryRun, warn, note
  * reading the template: `<repo_root>`, `<work_root>` and `<worktree_glob>` are resolved per run
  * (`docs/config.md` §4), which is the whole reason the profile is generated rather than copied.
  */
-export function renderProfile({ repoRoot, config, workRoot, written, writtenOuterLoop, referenceToolchainPath, force = false, dryRun = false, warn, note, }) {
+export function renderProfile({ repoRoot, config, workRoot, written, writtenOuterLoop, referenceToolchainPath, force = false, dryRun = false, pluginRootEntries: withPluginRootEntries = false, pluginRootOutcome, warn, note, }) {
     const scriptsDir = normalizeRepoDir(config.scriptsDir ?? DEFAULTS.scriptsDir);
     const stateDir = normalizeRepoDir(config.stateDir ?? DEFAULTS.stateDir);
     const projectName = config.projectName ?? defaultProjectName(repoRoot);
@@ -1155,6 +1222,22 @@ export function renderProfile({ repoRoot, config, workRoot, written, writtenOute
         ...(referenceToolchainPath === undefined ? {} : { referenceToolchainPath }),
         warn: warn ?? (() => { }),
     });
+    // In the same window, and before the carry-forward, whose `allow` check then skips every line
+    // generated here: one producer per line (module header).
+    let outcome = 'off';
+    if (withPluginRootEntries) {
+        const generated = generatedPluginRootEntries(repoRoot, config, warn ?? (() => { }));
+        if (generated === undefined) {
+            outcome = 'no-root';
+            (warn ?? (() => { }))(`${PLUGIN_ROOT_ENTRIES_FLAG} was given but ${installedPluginsPath()} records no plugin root on this machine, so no plugin-root entry was written: run \`claude plugin install\` for this plugin before init, then run init again`);
+        }
+        else {
+            outcome = 'appended';
+            appendAllow(profile, generated);
+            appendReadme(profile, `THE PLUGIN-ROOT ENTRIES WERE WRITTEN BY init ${PLUGIN_ROOT_ENTRIES_FLAG}: they name this machine's plugin roots, which carry the plugin version, so they go stale on an upgrade. The switch is for a profile that lives no longer than the install it names - a remote job's.`);
+        }
+    }
+    pluginRootOutcome?.(outcome);
     // In the same window and for the same reason: a carried plugin helper whose basename happens to
     // match a wrapper's would be counted as a fourth form of that wrapper above. Gated on `force`,
     // which is the only run that replaces the file these entries are read out of — an unforced render
@@ -1184,9 +1267,10 @@ export function renderProfile({ repoRoot, config, workRoot, written, writtenOute
  *
  * Nothing here touches the filesystem: the generator plans, and `init` applies the plan once.
  */
-export function writePermissionProfile({ repoRoot, config, plan, workRoot, written, writtenOuterLoop, referenceToolchainPath, force, dryRun, }) {
+export function writePermissionProfile({ repoRoot, config, plan, workRoot, written, writtenOuterLoop, referenceToolchainPath, force, dryRun, pluginRootEntries, }) {
     const warnings = [];
     const notes = [];
+    let outcome = 'off';
     const profile = renderProfile({
         repoRoot,
         config,
@@ -1196,6 +1280,10 @@ export function writePermissionProfile({ repoRoot, config, plan, workRoot, writt
         ...(referenceToolchainPath === undefined ? {} : { referenceToolchainPath }),
         ...(force === undefined ? {} : { force }),
         ...(dryRun === undefined ? {} : { dryRun }),
+        ...(pluginRootEntries === undefined ? {} : { pluginRootEntries }),
+        pluginRootOutcome: (value) => {
+            outcome = value;
+        },
         warn: (message) => warnings.push(message),
         note: (message) => notes.push(message),
     });
@@ -1209,6 +1297,7 @@ export function writePermissionProfile({ repoRoot, config, plan, workRoot, writt
             `${PROFILE_PATH} is committed, and it is machine-specific: the absolute paths in it are this checkout's, so a copy of this repository somewhere else needs doctor to re-check them and init --force to regenerate them. Select it per run with the agent runner's settings flag; it is never installed as the interactive default.`,
             ...notes,
         ],
+        pluginRootEntries: outcome,
     };
 }
 //# sourceMappingURL=permissionProfile.js.map