@tickernelz/paperclip-pro-shared 2026.925.0

package/dist/runner-goal.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export declare const RUNNER_GOAL_MAX_OBJECTIVE_CHARS = 4000;
+export declare const runnerGoalAvailabilitySchema: z.ZodEnum<{
+    available: "available";
+    policy_disabled: "policy_disabled";
+    unsupported: "unsupported";
+}>;
+export type RunnerGoalAvailability = z.infer<typeof runnerGoalAvailabilitySchema>;
+export declare const runnerGoalCapabilityActionSchema: z.ZodEnum<{
+    clear: "clear";
+    pause: "pause";
+    resume: "resume";
+    set: "set";
+}>;
+export type RunnerGoalCapabilityAction = z.infer<typeof runnerGoalCapabilityActionSchema>;
+export declare const runnerGoalStatusSchema: z.ZodEnum<{
+    active: "active";
+    blocked: "blocked";
+    budget_limited: "budget_limited";
+    complete: "complete";
+    limited: "limited";
+    paused: "paused";
+    usage_limited: "usage_limited";
+}>;
+export type RunnerGoalStatus = z.infer<typeof runnerGoalStatusSchema>;
+export declare const runnerGoalActionSchema: z.ZodEnum<{
+    clear: "clear";
+    create: "create";
+    edit: "edit";
+    pause: "pause";
+    replace: "replace";
+    resume: "resume";
+}>;
+export type RunnerGoalAction = z.infer<typeof runnerGoalActionSchema>;
+export declare const runnerGoalPendingActionSchema: z.ZodEnum<{
+    clearing: "clearing";
+    continuing: "continuing";
+    editing: "editing";
+    pausing: "pausing";
+    replacing: "replacing";
+    resuming: "resuming";
+    starting: "starting";
+}>;
+export type RunnerGoalPendingAction = z.infer<typeof runnerGoalPendingActionSchema>;
+export interface RunnerGoalCapability {
+    availability: RunnerGoalAvailability;
+    verified?: boolean;
+    actions: RunnerGoalCapabilityAction[];
+    autonomousUpdates: boolean;
+    persistentAcrossResume: boolean;
+    maxObjectiveChars: number;
+    tokenBudgetControl: boolean;
+    usageReporting: boolean;
+    reasonCode?: string | null;
+    reason?: string | null;
+}
+export interface RunnerGoalSnapshot {
+    objective: string;
+    status: RunnerGoalStatus;
+    tokenBudget: number | null;
+    tokensUsed: number;
+    elapsedSeconds: number;
+    iterations: number;
+    lastReason: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    completedAt: string | null;
+    workingNow: boolean;
+}
+export interface RunnerGoalProjection {
+    issueId: string;
+    agentId: string | null;
+    adapterType: string | null;
+    sessionId: string | null;
+    capability: RunnerGoalCapability;
+    goal: RunnerGoalSnapshot | null;
+    workingNow: boolean;
+    activeRunId: string | null;
+    pendingAction: RunnerGoalPendingAction | null;
+    revision: number;
+    observedAt: string | null;
+}
+export declare const runnerGoalActionRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    agentId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    action: z.ZodEnum<{
+        clear: "clear";
+        create: "create";
+        edit: "edit";
+        pause: "pause";
+        replace: "replace";
+        resume: "resume";
+    }>;
+    objective: z.ZodOptional<z.ZodString>;
+    tokenBudget: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    confirmReplace: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RunnerGoalActionRequest = z.infer<typeof runnerGoalActionRequestSchema>;
+export interface RunnerGoalActionAccepted {
+    requestId: string;
+    status: "accepted" | "pending" | "completed" | "failed";
+    projection: RunnerGoalProjection;
+}
+//# sourceMappingURL=runner-goal.d.ts.map

package/dist/runner-goal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-goal.d.ts","sourceRoot":"","sources":["../src/runner-goal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AAErD,eAAO,MAAM,4BAA4B;;;;EAIvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,gCAAgC;;;;;EAA8C,CAAC;AAC5F,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,sBAAsB;;;;;;;;EAQjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,sBAAsB;;;;;;;EAOjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,6BAA6B;;;;;;;;EAQxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,sBAAsB,CAAC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,0BAA0B,EAAE,CAAC;IACtC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sBAAsB,EAAE,OAAO,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,oBAAoB,CAAC;IACjC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAQD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;iBAiCtC,CAAC;AAEL,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACxD,UAAU,EAAE,oBAAoB,CAAC;CAClC"}

package/dist/runner-goal.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+export const RUNNER_GOAL_MAX_OBJECTIVE_CHARS = 4_000;
+export const runnerGoalAvailabilitySchema = z.enum([
+    "available",
+    "unsupported",
+    "policy_disabled",
+]);
+export const runnerGoalCapabilityActionSchema = z.enum(["set", "pause", "resume", "clear"]);
+export const runnerGoalStatusSchema = z.enum([
+    "active",
+    "paused",
+    "blocked",
+    "limited",
+    "usage_limited",
+    "budget_limited",
+    "complete",
+]);
+export const runnerGoalActionSchema = z.enum([
+    "create",
+    "edit",
+    "replace",
+    "pause",
+    "resume",
+    "clear",
+]);
+export const runnerGoalPendingActionSchema = z.enum([
+    "starting",
+    "editing",
+    "replacing",
+    "pausing",
+    "resuming",
+    "clearing",
+    "continuing",
+]);
+const objectiveSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(RUNNER_GOAL_MAX_OBJECTIVE_CHARS);
+export const runnerGoalActionRequestSchema = z
+    .object({
+    requestId: z.string().trim().min(1).max(160),
+    agentId: z.string().uuid(),
+    expectedRevision: z.number().int().nonnegative(),
+    action: runnerGoalActionSchema,
+    objective: objectiveSchema.optional(),
+    tokenBudget: z.number().int().positive().nullable().optional(),
+    confirmReplace: z.boolean().optional(),
+})
+    .superRefine((value, context) => {
+    const objectiveAction = value.action === "create" || value.action === "edit" || value.action === "replace";
+    if (objectiveAction && value.objective === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["objective"],
+            message: `${value.action} requires a nonblank objective`,
+        });
+    }
+    if (!objectiveAction && (value.objective !== undefined || value.tokenBudget !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            path: [value.objective !== undefined ? "objective" : "tokenBudget"],
+            message: `${value.action} does not accept an objective or token budget`,
+        });
+    }
+    if (value.action === "replace" && value.confirmReplace !== true) {
+        context.addIssue({
+            code: "custom",
+            path: ["confirmReplace"],
+            message: "replace requires explicit confirmation",
+        });
+    }
+});
+//# sourceMappingURL=runner-goal.js.map

package/dist/runner-goal.js.map

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

package/dist/runtime-exposure/loopback-bind.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Forcing a managed runtime's listeners onto loopback through argv (PAP-17256).
+ *
+ * The broker only exposes a port whose listener /proc proves to be loopback-only,
+ * so an exposed Paperclip dev runtime MUST bind `127.0.0.1`. The server used to
+ * request that with env vars alone (`PAPERCLIP_BIND` / `PAPERCLIP_BIND_HOST`),
+ * which is not sufficient: the process that has to honour them is the *guest
+ * checkout's* `scripts/dev-runner.ts`, and a checkout that predates managed
+ * exposure overwrites `PAPERCLIP_BIND` from its own `--bind` argv and deletes
+ * `PAPERCLIP_BIND_HOST` outright. A branch pinned at such a commit therefore
+ * bound `0.0.0.0` and every expose was correctly denied with
+ * `listener_ownership_mismatch`.
+ *
+ * argv is the one channel every dev-runner version honours, because each of them
+ * derives its bind mode from `--bind` / `--bind-host` *before* writing the child
+ * env. Rewriting the command is what actually makes the loopback bind binding.
+ *
+ * Pure string functions only — no I/O, no process state.
+ */
+/** The only bind preset an exposed managed runtime may use. */
+export declare const RUNTIME_EXPOSURE_BIND_MODE = "loopback";
+export declare const RUNTIME_EXPOSURE_BIND_HOST = "127.0.0.1";
+/** True when the command carries an explicit bind selection of any kind. */
+export declare function commandSelectsBindMode(command: string): boolean;
+export declare function isPaperclipDevRunnerCommand(command: string): boolean;
+/**
+ * Rewrite a Paperclip dev-runner command so it explicitly requests the loopback
+ * bind, replacing whatever bind selection it carried.
+ *
+ * A command that is not a dev-runner invocation is returned untouched — see
+ * {@link isPaperclipDevRunnerCommand} for why that guard is not optional.
+ *
+ * The legacy `--tailscale-auth` / `--authenticated-private` aliases are
+ * deliberately *left in place*: an explicit `--bind` already wins over them in
+ * every dev-runner version, they still correctly select the authenticated
+ * deployment mode an exposed lane wants, and `isPaperclipDevRuntimeService`
+ * matches on `--tailscale-auth` as a substring, so stripping it would silently
+ * change readiness handling.
+ */
+export declare function forceLoopbackBindInCommand(command: string): string;
+/**
+ * Point a probe URL at loopback, keeping its scheme, port, and path.
+ *
+ * An exposed runtime's listener is loopback-only by construction, so probing it
+ * on any other host cannot work. The live config happens to declare a loopback
+ * readiness URL, but the fallback target is the service's display URL — a
+ * MagicDNS name like `http://paperclip-dev:42003` — which only ever answered
+ * because the guest was wrongly bound to the wildcard. Normalising here keeps
+ * the loopback fix from turning that latent mismatch into a readiness timeout.
+ */
+export declare function rewriteUrlHostToLoopback(url: string | null): string | null;
+//# sourceMappingURL=loopback-bind.d.ts.map

package/dist/runtime-exposure/loopback-bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-bind.d.ts","sourceRoot":"","sources":["../../src/runtime-exposure/loopback-bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,aAAa,CAAC;AACrD,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAYtD,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG/D;AAcD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAU1E"}

package/dist/runtime-exposure/loopback-bind.js

@@ -0,0 +1,93 @@
+/**
+ * Forcing a managed runtime's listeners onto loopback through argv (PAP-17256).
+ *
+ * The broker only exposes a port whose listener /proc proves to be loopback-only,
+ * so an exposed Paperclip dev runtime MUST bind `127.0.0.1`. The server used to
+ * request that with env vars alone (`PAPERCLIP_BIND` / `PAPERCLIP_BIND_HOST`),
+ * which is not sufficient: the process that has to honour them is the *guest
+ * checkout's* `scripts/dev-runner.ts`, and a checkout that predates managed
+ * exposure overwrites `PAPERCLIP_BIND` from its own `--bind` argv and deletes
+ * `PAPERCLIP_BIND_HOST` outright. A branch pinned at such a commit therefore
+ * bound `0.0.0.0` and every expose was correctly denied with
+ * `listener_ownership_mismatch`.
+ *
+ * argv is the one channel every dev-runner version honours, because each of them
+ * derives its bind mode from `--bind` / `--bind-host` *before* writing the child
+ * env. Rewriting the command is what actually makes the loopback bind binding.
+ *
+ * Pure string functions only — no I/O, no process state.
+ */
+/** The only bind preset an exposed managed runtime may use. */
+export const RUNTIME_EXPOSURE_BIND_MODE = "loopback";
+export const RUNTIME_EXPOSURE_BIND_HOST = "127.0.0.1";
+/**
+ * `--bind <mode>` / `--bind-host <host>`, in both the space- and `=`-separated
+ * spellings. Each takes exactly one value, and a value is never another flag.
+ */
+const BIND_SELECTING_ARG = /(?:^|\s)--bind(?:-host)?(?:=|\s+)(?!--)[^\s]+/g;
+/** Legacy aliases for `--bind lan`; they select a non-loopback bind. */
+const LEGACY_LAN_ALIASES = /(?:^|\s)--(?:tailscale-auth|authenticated-private)(?=\s|$)/g;
+/** True when the command carries an explicit bind selection of any kind. */
+export function commandSelectsBindMode(command) {
+    return new RegExp(BIND_SELECTING_ARG.source).test(command)
+        || new RegExp(LEGACY_LAN_ALIASES.source).test(command);
+}
+/**
+ * A Paperclip dev-runner invocation — the only shape that understands
+ * `--bind` / `--bind-host`.
+ *
+ * Deliberately keyed on the *command*, not the service name. `--bind` means
+ * something entirely different to an unrelated process (the HTTPS probe canaries
+ * pass it to `python3 -m http.server`), and appending flags a command does not
+ * parse turns a working service into one that exits on startup.
+ */
+const PAPERCLIP_DEV_RUNNER_COMMAND = /(?:^|[\s;&|])(?:(?:pnpm|npm|yarn|bun)(?:\s+run)?\s+dev(?::once|:watch|:server)?(?=\s|$)|[^\s]*dev-runner(?:\.[cm]?[jt]s)?(?=\s|$))/;
+export function isPaperclipDevRunnerCommand(command) {
+    return PAPERCLIP_DEV_RUNNER_COMMAND.test(command);
+}
+/**
+ * Rewrite a Paperclip dev-runner command so it explicitly requests the loopback
+ * bind, replacing whatever bind selection it carried.
+ *
+ * A command that is not a dev-runner invocation is returned untouched — see
+ * {@link isPaperclipDevRunnerCommand} for why that guard is not optional.
+ *
+ * The legacy `--tailscale-auth` / `--authenticated-private` aliases are
+ * deliberately *left in place*: an explicit `--bind` already wins over them in
+ * every dev-runner version, they still correctly select the authenticated
+ * deployment mode an exposed lane wants, and `isPaperclipDevRuntimeService`
+ * matches on `--tailscale-auth` as a substring, so stripping it would silently
+ * change readiness handling.
+ */
+export function forceLoopbackBindInCommand(command) {
+    if (!isPaperclipDevRunnerCommand(command))
+        return command;
+    const stripped = command.replace(BIND_SELECTING_ARG, "").trim();
+    if (stripped.length === 0)
+        return command;
+    return `${stripped} --bind ${RUNTIME_EXPOSURE_BIND_MODE}`;
+}
+/**
+ * Point a probe URL at loopback, keeping its scheme, port, and path.
+ *
+ * An exposed runtime's listener is loopback-only by construction, so probing it
+ * on any other host cannot work. The live config happens to declare a loopback
+ * readiness URL, but the fallback target is the service's display URL — a
+ * MagicDNS name like `http://paperclip-dev:42003` — which only ever answered
+ * because the guest was wrongly bound to the wildcard. Normalising here keeps
+ * the loopback fix from turning that latent mismatch into a readiness timeout.
+ */
+export function rewriteUrlHostToLoopback(url) {
+    if (!url)
+        return url;
+    try {
+        const parsed = new URL(url);
+        parsed.hostname = RUNTIME_EXPOSURE_BIND_HOST;
+        return parsed.toString();
+    }
+    catch {
+        // Not a URL we can reason about; leave it for the caller's own handling.
+        return url;
+    }
+}
+//# sourceMappingURL=loopback-bind.js.map

package/dist/runtime-exposure/loopback-bind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-bind.js","sourceRoot":"","sources":["../../src/runtime-exposure/loopback-bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CAAC;AAEtD;;;GAGG;AACH,MAAM,kBAAkB,GACtB,gDAAgD,CAAC;AAEnD,wEAAwE;AACxE,MAAM,kBAAkB,GAAG,6DAA6D,CAAC;AAEzF,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;WACrD,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,4BAA4B,GAChC,oIAAoI,CAAC;AAEvI,MAAM,UAAU,2BAA2B,CAAC,OAAe;IACzD,OAAO,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAe;IACxD,IAAI,CAAC,2BAA2B,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,GAAG,QAAQ,WAAW,0BAA0B,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAkB;IACzD,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,CAAC,QAAQ,GAAG,0BAA0B,CAAC;QAC7C,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/runtime-exposure/loopback-bind.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loopback-bind.test.d.ts.map

package/dist/runtime-exposure/loopback-bind.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-bind.test.d.ts","sourceRoot":"","sources":["../../src/runtime-exposure/loopback-bind.test.ts"],"names":[],"mappings":""}

package/dist/runtime-exposure/loopback-bind.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { RUNTIME_EXPOSURE_BIND_HOST, commandSelectsBindMode, forceLoopbackBindInCommand, isPaperclipDevRunnerCommand, rewriteUrlHostToLoopback, } from "./loopback-bind.js";
+describe("forceLoopbackBindInCommand", () => {
+    it("replaces the exact command the failing managed lanes ran", () => {
+        // PAP-17256 reproduction: this is verbatim what `workspace_runtime_services`
+        // recorded for every lane the broker denied.
+        expect(forceLoopbackBindInCommand("pnpm dev --bind lan")).toBe("pnpm dev --bind loopback");
+    });
+    it("replaces an existing loopback-adjacent bind rather than duplicating it", () => {
+        expect(forceLoopbackBindInCommand("pnpm dev --bind tailnet")).toBe("pnpm dev --bind loopback");
+        expect(forceLoopbackBindInCommand("pnpm dev --bind custom --bind-host 10.0.0.4")).toBe("pnpm dev --bind loopback");
+    });
+    it("is idempotent, so a re-start of an already-rewritten service is stable", () => {
+        const once = forceLoopbackBindInCommand("pnpm dev --bind lan");
+        expect(forceLoopbackBindInCommand(once)).toBe(once);
+    });
+    it("handles the =-separated spelling", () => {
+        expect(forceLoopbackBindInCommand("pnpm dev --bind=lan --bind-host=0.0.0.0")).toBe("pnpm dev --bind loopback");
+    });
+    it("adds an explicit loopback bind when the command selects none", () => {
+        // A bare `pnpm dev` lets an old guest runner infer its bind from HOST, so the
+        // flags must be added rather than assumed.
+        expect(forceLoopbackBindInCommand("pnpm dev")).toBe("pnpm dev --bind loopback");
+    });
+    it("keeps the legacy lan aliases so dev-service detection still matches", () => {
+        // `isPaperclipDevRuntimeService` matches `--tailscale-auth` as a substring;
+        // an explicit `--bind` already beats the alias in every dev-runner version.
+        expect(forceLoopbackBindInCommand("pnpm dev:once --tailscale-auth")).toBe("pnpm dev:once --tailscale-auth --bind loopback");
+    });
+    it("never strips a value that is actually the next flag", () => {
+        expect(forceLoopbackBindInCommand("pnpm dev --bind --verbose")).toBe("pnpm dev --bind --verbose --bind loopback");
+    });
+    it("does not touch a --bind occurrence that is not a flag boundary", () => {
+        expect(forceLoopbackBindInCommand("pnpm dev --no--bind lan")).toBe("pnpm dev --no--bind lan --bind loopback");
+    });
+    it("leaves a command that does not parse these flags untouched", () => {
+        // The HTTPS probe canaries: rewriting this would produce nonsense, and
+        // appending flags to a command that cannot parse them makes it exit at boot.
+        const canary = 'python3 -m http.server "$PORT" --bind 127.0.0.1';
+        expect(forceLoopbackBindInCommand(canary)).toBe(canary);
+        const fixture = `node -e 'require("http").createServer().listen(1)'`;
+        expect(forceLoopbackBindInCommand(fixture)).toBe(fixture);
+    });
+    it("uses the loopback preset without turning it into a custom bind", () => {
+        expect(forceLoopbackBindInCommand("pnpm dev")).toBe("pnpm dev --bind loopback");
+        expect(RUNTIME_EXPOSURE_BIND_HOST).toBe("127.0.0.1");
+    });
+});
+describe("commandSelectsBindMode", () => {
+    it("detects both spellings and the legacy aliases", () => {
+        expect(commandSelectsBindMode("pnpm dev --bind lan")).toBe(true);
+        expect(commandSelectsBindMode("pnpm dev --bind=lan")).toBe(true);
+        expect(commandSelectsBindMode("pnpm dev --bind-host 10.0.0.1")).toBe(true);
+        expect(commandSelectsBindMode("pnpm dev:once --tailscale-auth")).toBe(true);
+        expect(commandSelectsBindMode("pnpm dev:once --authenticated-private")).toBe(true);
+    });
+    it("is false for a command with no bind selection", () => {
+        expect(commandSelectsBindMode("pnpm dev")).toBe(false);
+        expect(commandSelectsBindMode('python3 -m http.server "$PORT"')).toBe(false);
+    });
+});
+describe("isPaperclipDevRunnerCommand", () => {
+    it("matches the real managed dev commands", () => {
+        expect(isPaperclipDevRunnerCommand("pnpm dev --bind lan")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("pnpm dev")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("pnpm dev:once --tailscale-auth")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("pnpm dev:watch")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("npm run dev --bind lan")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("yarn dev")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("node /tmp/x/dev-runner.mjs --bind lan")).toBe(true);
+        expect(isPaperclipDevRunnerCommand("tsx ../scripts/dev-runner.ts watch")).toBe(true);
+    });
+    it("does not match unrelated commands that merely use --bind", () => {
+        expect(isPaperclipDevRunnerCommand('python3 -m http.server "$PORT" --bind 127.0.0.1')).toBe(false);
+        expect(isPaperclipDevRunnerCommand("node -e 'listen()'")).toBe(false);
+        expect(isPaperclipDevRunnerCommand("pnpm build")).toBe(false);
+        expect(isPaperclipDevRunnerCommand("pnpm develop")).toBe(false);
+        expect(isPaperclipDevRunnerCommand("./my-dev-runnerish --bind lan")).toBe(false);
+    });
+});
+describe("rewriteUrlHostToLoopback", () => {
+    it("redirects a MagicDNS probe target to loopback, keeping port and path", () => {
+        expect(rewriteUrlHostToLoopback("http://paperclip-dev:42003/api/health")).toBe("http://127.0.0.1:42003/api/health");
+        expect(rewriteUrlHostToLoopback("http://paperclip-dev:42003")).toBe("http://127.0.0.1:42003/");
+    });
+    it("leaves an already-loopback target alone", () => {
+        expect(rewriteUrlHostToLoopback("http://127.0.0.1:42003/api/health")).toBe("http://127.0.0.1:42003/api/health");
+    });
+    it("passes through null and unparseable values", () => {
+        expect(rewriteUrlHostToLoopback(null)).toBeNull();
+        expect(rewriteUrlHostToLoopback("not a url")).toBe("not a url");
+    });
+});
+//# sourceMappingURL=loopback-bind.test.js.map

package/dist/runtime-exposure/loopback-bind.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-bind.test.js","sourceRoot":"","sources":["../../src/runtime-exposure/loopback-bind.test.ts"],"names":[],"mappings":"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"}

package/dist/runtime-exposure/ports.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deterministic, shared port + URL derivation for the `tailscale_https`
+ * exposure mode. Extracted so runtime allocation, server startup, the broker,
+ * and tests all agree on the dedicated Paperclip runtime port range and the
+ * app/HMR pairing (PAP-17049 plan, PAP-17050 verdict requirement #2).
+ *
+ * Pure functions only — no I/O, no process state.
+ */
+/**
+ * Dedicated, allowlisted port range for managed Paperclip runtime APP
+ * listeners. Ports outside this range are never eligible for exposure, which
+ * bounds the SSRF blast radius: a compromised caller cannot ask the broker to
+ * publish an arbitrary existing loopback service.
+ */
+export declare const RUNTIME_EXPOSURE_APP_PORT_MIN = 42000;
+export declare const RUNTIME_EXPOSURE_APP_PORT_MAX = 42999;
+/**
+ * Fixed offset between an app port and its Paperclip Vite HMR companion port.
+ * Matches Paperclip dev mode's `server port + offset` HMR convention and keeps
+ * the two listeners deterministically paired.
+ */
+export declare const RUNTIME_EXPOSURE_HMR_PORT_OFFSET = 10000;
+/** Derived HMR companion port range, kept in sync with the offset above. */
+export declare const RUNTIME_EXPOSURE_HMR_PORT_MIN: number;
+export declare const RUNTIME_EXPOSURE_HMR_PORT_MAX: number;
+/** True only for integers strictly inside the dedicated app port range. */
+export declare function isRuntimeExposureAppPort(port: number): boolean;
+/** True only for integers strictly inside the derived HMR companion range. */
+export declare function isRuntimeExposureHmrPort(port: number): boolean;
+/**
+ * True for any port the broker is allowed to expose (app OR HMR companion).
+ * Everything else — privileged/reserved ports, `443`, ephemeral, unknown — is
+ * deny-by-default.
+ */
+export declare function isAllowedRuntimeExposurePort(port: number): boolean;
+/**
+ * Derive the Vite HMR companion port for an allocated app port. Throws if the
+ * app port is not a valid dedicated app port so callers cannot silently pair a
+ * port outside the allowlist.
+ */
+export declare function deriveViteHmrPort(appPort: number): number;
+/**
+ * Derive Paperclip's Vite HMR companion port for any valid application port.
+ *
+ * Normal Paperclip instances can use ports outside the dedicated exposure
+ * range, while exposed branch runtimes are deliberately constrained to it.
+ * Keeping the generic derivation here prevents the app server and exposure
+ * allocator from drifting while preserving the historical overflow fallback.
+ */
+export declare function derivePaperclipViteHmrPort(serverPort: number): number;
+/**
+ * Build the canonical browser URL for an exposed app port on a resolved
+ * Tailscale node hostname. Uses the non-standard HTTPS port explicitly.
+ */
+export declare function buildRuntimeExposureUrl(hostname: string, appPort: number): string;
+/**
+ * Build the external HTTPS health-probe URL used to verify normal certificate
+ * validation before a runtime is reported healthy.
+ */
+export declare function buildRuntimeExposureHealthUrl(hostname: string, appPort: number): string;
+//# sourceMappingURL=ports.d.ts.map

package/dist/runtime-exposure/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/runtime-exposure/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAQ,CAAC;AACnD,eAAO,MAAM,6BAA6B,QAAQ,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,QAAQ,CAAC;AAEtD,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,QACwB,CAAC;AACnE,eAAO,MAAM,6BAA6B,QACwB,CAAC;AAEnE,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9D;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CASjF;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvF"}

package/dist/runtime-exposure/ports.js

@@ -0,0 +1,96 @@
+/**
+ * Deterministic, shared port + URL derivation for the `tailscale_https`
+ * exposure mode. Extracted so runtime allocation, server startup, the broker,
+ * and tests all agree on the dedicated Paperclip runtime port range and the
+ * app/HMR pairing (PAP-17049 plan, PAP-17050 verdict requirement #2).
+ *
+ * Pure functions only — no I/O, no process state.
+ */
+/**
+ * Dedicated, allowlisted port range for managed Paperclip runtime APP
+ * listeners. Ports outside this range are never eligible for exposure, which
+ * bounds the SSRF blast radius: a compromised caller cannot ask the broker to
+ * publish an arbitrary existing loopback service.
+ */
+export const RUNTIME_EXPOSURE_APP_PORT_MIN = 42000;
+export const RUNTIME_EXPOSURE_APP_PORT_MAX = 42999;
+/**
+ * Fixed offset between an app port and its Paperclip Vite HMR companion port.
+ * Matches Paperclip dev mode's `server port + offset` HMR convention and keeps
+ * the two listeners deterministically paired.
+ */
+export const RUNTIME_EXPOSURE_HMR_PORT_OFFSET = 10000;
+/** Derived HMR companion port range, kept in sync with the offset above. */
+export const RUNTIME_EXPOSURE_HMR_PORT_MIN = RUNTIME_EXPOSURE_APP_PORT_MIN + RUNTIME_EXPOSURE_HMR_PORT_OFFSET;
+export const RUNTIME_EXPOSURE_HMR_PORT_MAX = RUNTIME_EXPOSURE_APP_PORT_MAX + RUNTIME_EXPOSURE_HMR_PORT_OFFSET;
+/** True only for integers strictly inside the dedicated app port range. */
+export function isRuntimeExposureAppPort(port) {
+    return (Number.isInteger(port) &&
+        port >= RUNTIME_EXPOSURE_APP_PORT_MIN &&
+        port <= RUNTIME_EXPOSURE_APP_PORT_MAX);
+}
+/** True only for integers strictly inside the derived HMR companion range. */
+export function isRuntimeExposureHmrPort(port) {
+    return (Number.isInteger(port) &&
+        port >= RUNTIME_EXPOSURE_HMR_PORT_MIN &&
+        port <= RUNTIME_EXPOSURE_HMR_PORT_MAX);
+}
+/**
+ * True for any port the broker is allowed to expose (app OR HMR companion).
+ * Everything else — privileged/reserved ports, `443`, ephemeral, unknown — is
+ * deny-by-default.
+ */
+export function isAllowedRuntimeExposurePort(port) {
+    return isRuntimeExposureAppPort(port) || isRuntimeExposureHmrPort(port);
+}
+/**
+ * Derive the Vite HMR companion port for an allocated app port. Throws if the
+ * app port is not a valid dedicated app port so callers cannot silently pair a
+ * port outside the allowlist.
+ */
+export function deriveViteHmrPort(appPort) {
+    if (!isRuntimeExposureAppPort(appPort)) {
+        throw new RangeError(`app port ${appPort} is outside the dedicated runtime exposure range ` +
+            `[${RUNTIME_EXPOSURE_APP_PORT_MIN}, ${RUNTIME_EXPOSURE_APP_PORT_MAX}]`);
+    }
+    return derivePaperclipViteHmrPort(appPort);
+}
+/**
+ * Derive Paperclip's Vite HMR companion port for any valid application port.
+ *
+ * Normal Paperclip instances can use ports outside the dedicated exposure
+ * range, while exposed branch runtimes are deliberately constrained to it.
+ * Keeping the generic derivation here prevents the app server and exposure
+ * allocator from drifting while preserving the historical overflow fallback.
+ */
+export function derivePaperclipViteHmrPort(serverPort) {
+    if (!Number.isInteger(serverPort) || serverPort < 1 || serverPort > 65_535) {
+        throw new RangeError(`server port ${serverPort} is not a valid TCP port`);
+    }
+    if (serverPort <= 55_535) {
+        return serverPort + RUNTIME_EXPOSURE_HMR_PORT_OFFSET;
+    }
+    return Math.max(1_024, serverPort - RUNTIME_EXPOSURE_HMR_PORT_OFFSET);
+}
+/**
+ * Build the canonical browser URL for an exposed app port on a resolved
+ * Tailscale node hostname. Uses the non-standard HTTPS port explicitly.
+ */
+export function buildRuntimeExposureUrl(hostname, appPort) {
+    const trimmed = hostname.trim();
+    if (trimmed.length === 0) {
+        throw new Error("hostname is required to build an exposure URL");
+    }
+    if (!isRuntimeExposureAppPort(appPort)) {
+        throw new RangeError(`app port ${appPort} is outside the dedicated runtime exposure range`);
+    }
+    return `https://${trimmed}:${appPort}`;
+}
+/**
+ * Build the external HTTPS health-probe URL used to verify normal certificate
+ * validation before a runtime is reported healthy.
+ */
+export function buildRuntimeExposureHealthUrl(hostname, appPort) {
+    return `${buildRuntimeExposureUrl(hostname, appPort)}/api/health`;
+}
+//# sourceMappingURL=ports.js.map

package/dist/runtime-exposure/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/runtime-exposure/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,KAAK,CAAC;AACnD,MAAM,CAAC,MAAM,6BAA6B,GAAG,KAAK,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,KAAK,CAAC;AAEtD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GACxC,6BAA6B,GAAG,gCAAgC,CAAC;AACnE,MAAM,CAAC,MAAM,6BAA6B,GACxC,6BAA6B,GAAG,gCAAgC,CAAC;AAEnE,2EAA2E;AAC3E,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,CACL,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC;QACtB,IAAI,IAAI,6BAA6B;QACrC,IAAI,IAAI,6BAA6B,CACtC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,CACL,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC;QACtB,IAAI,IAAI,6BAA6B;QACrC,IAAI,IAAI,6BAA6B,CACtC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAY;IACvD,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAClB,YAAY,OAAO,mDAAmD;YACpE,IAAI,6BAA6B,KAAK,6BAA6B,GAAG,CACzE,CAAC;IACJ,CAAC;IACD,OAAO,0BAA0B,CAAC,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAAkB;IAC3D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,MAAM,EAAE,CAAC;QAC3E,MAAM,IAAI,UAAU,CAAC,eAAe,UAAU,0BAA0B,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;QACzB,OAAO,UAAU,GAAG,gCAAgC,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,gCAAgC,CAAC,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB,EAAE,OAAe;IACvE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAAC,YAAY,OAAO,kDAAkD,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,WAAW,OAAO,IAAI,OAAO,EAAE,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAgB,EAAE,OAAe;IAC7E,OAAO,GAAG,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC;AACpE,CAAC"}

package/dist/runtime-exposure/ports.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.test.d.ts.map

package/dist/runtime-exposure/ports.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.test.d.ts","sourceRoot":"","sources":["../../src/runtime-exposure/ports.test.ts"],"names":[],"mappings":""}