@av-pi-studio/server 0.0.1

package/dist/projects/worktree-service.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { defaultGitRunner } from "./git-detect.js";
+import { normalizePath, WorkspaceRegistryService } from "./workspace-registry.js";
+/**
+ * Pi-Studio-managed git worktree service (features/worktrees.md § Operations, § Behavior,
+ * § Lifecycle config; architecture/agent-lifecycle.md § Archive). Handles create/setup, archive/
+ * teardown, and the `autoArchive`+`worktree` coupling.
+ */
+/** Agent label naming the worktree workspace it lives in (for auto-archive coupling). */
+export const WORKTREE_WORKSPACE_ID_LABEL = "pi-studio.worktree-workspace-id";
+/** Agent label flagging auto-archive after the first terminal turn. */
+export const AUTO_ARCHIVE_LABEL = "pi-studio.auto-archive";
+const MAX_WORKTREE_NAME = 60;
+/** Slug a branch/worktree name: lowercase, keep `[a-z0-9-/]`, collapse separators. */
+export function slugBranchName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9/\s_-]/g, "")
+        .replace(/[\s_]+/g, "-")
+        .replace(/\/+/g, "/")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-/]+|[-/]+$/g, "");
+    return slug || "work";
+}
+/**
+ * Resolve a unique, length-bounded worktree name. Over-long names are truncated and a deterministic
+ * 7-char hash suffix is appended; colliding names get a deterministic suffix that increments a salt
+ * until unique within `existing`.
+ */
+export function resolveWorktreeName(rawName, existing, maxLen = MAX_WORKTREE_NAME) {
+    const base = slugBranchName(rawName);
+    if (base.length <= maxLen && !existing.has(base))
+        return base;
+    const room = Math.max(1, maxLen - 8); // 1 sep + 7 hash chars
+    const truncated = base.slice(0, room).replace(/[-/]+$/, "");
+    for (let salt = 0; salt < 1000; salt++) {
+        const hash = createHash("sha256").update(`${rawName}:${salt}`).digest("hex").slice(0, 7);
+        const candidate = `${truncated}-${hash}`;
+        if (!existing.has(candidate))
+            return candidate;
+    }
+    // Extremely unlikely fallthrough.
+    return `${truncated}-${createHash("sha256").update(rawName).digest("hex").slice(0, 12)}`;
+}
+export class WorktreeService {
+    deps;
+    registry;
+    git;
+    runCommand;
+    constructor(deps) {
+        this.deps = deps;
+        this.registry = deps.registry ?? new WorkspaceRegistryService(deps.home);
+        this.git = deps.gitRunner ?? defaultGitRunner;
+        this.runCommand = deps.runCommand ?? (async () => ({ code: 0, stdout: "", stderr: "" }));
+    }
+    registerHandlers(registry, getActiveSessions) {
+        registry.register("create_pistudio_worktree_request", async (ctx) => {
+            const descriptor = await this.createWorktree({
+                projectRoot: String(ctx.message.projectRoot ?? ctx.message.cwd ?? ""),
+                projectId: String(ctx.message.projectId ?? ""),
+                name: ctx.message.name,
+                branch: ctx.message.branch,
+                baseRef: ctx.message.baseRef,
+                generatePrompt: ctx.message.generatePrompt,
+            }, getActiveSessions);
+            return { type: "create_pistudio_worktree_response", worktree: descriptor };
+        });
+        registry.register("pistudio_worktree_list_request", async () => ({
+            type: "pistudio_worktree_list_response",
+            worktrees: (await this.registry.listActiveWorkspaces()).filter((w) => w.kind === "worktree"),
+        }));
+        registry.register("pistudio_worktree_archive_request", async (ctx) => {
+            const workspaceId = String(ctx.message.workspaceId ?? "");
+            const ok = await this.archiveWorktree(workspaceId, getActiveSessions);
+            return { type: "pistudio_worktree_archive_response", workspaceId, ok };
+        });
+    }
+    worktreeRoot() {
+        return this.deps.worktreeRoot ?? join(this.deps.home, "worktrees");
+    }
+    /** Create a Pi-Studio worktree, register it, and run `setup`. */
+    async createWorktree(intent, getActiveSessions = this.deps.getActiveSessions ?? (() => [])) {
+        const root = this.worktreeRoot();
+        // Existing worktree names occupied under the root (from the active registry).
+        const occupied = new Set((await this.registry.listActiveWorkspaces())
+            .filter((w) => w.kind === "worktree")
+            .map((w) => basename(w.cwd)));
+        // Resolve target branch + worktree name.
+        let branch;
+        let isNewBranch;
+        if (intent.branch && intent.branch.trim().length > 0) {
+            branch = intent.branch.trim();
+            isNewBranch = false;
+        }
+        else {
+            const raw = intent.name?.trim() ||
+                (intent.generatePrompt && this.deps.generateBranchName
+                    ? await this.deps.generateBranchName(intent.generatePrompt)
+                    : "") ||
+                intent.generatePrompt ||
+                "work";
+            branch = slugBranchName(raw);
+            isNewBranch = true;
+        }
+        const name = resolveWorktreeName(intent.name?.trim() || branch, occupied);
+        const path = join(root, name);
+        const args = isNewBranch
+            ? ["worktree", "add", "-b", branch, path, ...(intent.baseRef ? [intent.baseRef] : [])]
+            : ["worktree", "add", path, branch];
+        const added = await this.git(args, intent.projectRoot);
+        if (added.code !== 0) {
+            throw new Error(`git worktree add failed: ${added.stdout}`.trim());
+        }
+        const { workspace } = await this.registry.resolveOrCreateWorkspace({
+            projectId: intent.projectId,
+            cwd: path,
+            kind: "worktree",
+            displayName: name,
+        });
+        const setupOk = await this.runLifecycle("setup", intent.projectRoot, path, getActiveSessions);
+        this.deps.broadcast(getActiveSessions(), {
+            type: "workspace_update",
+            workspaceId: workspace.workspaceId,
+            projectId: workspace.projectId,
+            cwd: workspace.cwd,
+            kind: "worktree",
+            displayName: workspace.displayName,
+            archivedAt: null,
+            branch,
+        });
+        return { workspace, name, branch, path, setupOk };
+    }
+    /** Archive a worktree: teardown → archive contained agents → `git worktree remove`/prune. */
+    async archiveWorktree(workspaceId, getActiveSessions = this.deps.getActiveSessions ?? (() => [])) {
+        const workspaces = await this.registry.listWorkspaces();
+        const workspace = workspaces.find((w) => w.workspaceId === workspaceId);
+        if (!workspace || workspace.archivedAt)
+            return false;
+        const path = workspace.cwd;
+        await this.runLifecycle("teardown", null, path, getActiveSessions);
+        // Archive every agent whose cwd is inside the worktree.
+        const inside = (this.deps.listAgents?.() ?? []).filter((a) => isInside(path, a.cwd));
+        for (const agent of inside) {
+            await this.deps.archiveAgent?.(agent.id);
+        }
+        // Remove + prune the git worktree (best-effort; ignore failure so the record still archives).
+        await this.git(["worktree", "remove", "--force", path], path).catch(() => undefined);
+        await this.git(["worktree", "prune"], path).catch(() => undefined);
+        const archived = await this.registry.archiveWorkspace(workspaceId);
+        if (archived) {
+            this.deps.broadcast(getActiveSessions(), {
+                type: "workspace_update",
+                workspaceId,
+                archivedAt: archived.archivedAt,
+                kind: "worktree",
+            });
+        }
+        return true;
+    }
+    /**
+     * Auto-archive coupling: when an agent created with `autoArchive` + a `worktree` target reaches a
+     * terminal turn, archive the agent AND its worktree (which cascades to any agents inside it).
+     * Returns true when an auto-archive was performed.
+     */
+    async maybeAutoArchiveOnTerminalTurn(agent, getActiveSessions = this.deps.getActiveSessions ?? (() => [])) {
+        const autoArchive = agent.labels[AUTO_ARCHIVE_LABEL] === "true";
+        const worktreeId = agent.labels[WORKTREE_WORKSPACE_ID_LABEL];
+        if (!autoArchive || !worktreeId)
+            return false;
+        return this.archiveWorktree(worktreeId, getActiveSessions);
+    }
+    async runLifecycle(phase, sourceCheckoutPath, worktreePath, getActiveSessions) {
+        const lifecycle = this.deps.readWorktreeLifecycle
+            ? await this.deps.readWorktreeLifecycle(sourceCheckoutPath ?? worktreePath)
+            : { setup: [], teardown: [] };
+        const commands = lifecycle[phase];
+        if (commands.length === 0)
+            return true;
+        const env = {
+            PI_STUDIO_WORKTREE_PATH: worktreePath,
+            PI_STUDIO_SOURCE_CHECKOUT_PATH: sourceCheckoutPath ?? worktreePath,
+        };
+        let ok = true;
+        for (let i = 0; i < commands.length; i++) {
+            const command = commands[i];
+            const result = await this.runCommand(command, { cwd: worktreePath, env });
+            this.deps.broadcast(getActiveSessions(), {
+                type: "workspace_setup_progress",
+                worktreePath,
+                phase,
+                index: i,
+                total: commands.length,
+                command,
+                code: result.code,
+            });
+            if (result.code !== 0) {
+                ok = false;
+                break; // surface the failure; worktree remains for inspection
+            }
+        }
+        return ok;
+    }
+}
+function basename(p) {
+    const norm = normalizePath(p);
+    const parts = norm.split("/");
+    return parts[parts.length - 1] || norm;
+}
+/** True when `child` is the worktree path or nested under it. */
+function isInside(root, child) {
+    const r = normalizePath(root);
+    const c = normalizePath(child);
+    return c === r || c.startsWith(`${r}/`);
+}
+//# sourceMappingURL=worktree-service.js.map

package/dist/projects/worktree-service.js.map

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

package/dist/proxy/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./service-hostname.js";
+export * from "./service-port-registry.js";
+export * from "./service-proxy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/proxy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC"}

package/dist/proxy/index.js

@@ -0,0 +1,5 @@
+// HTTP service proxy: generated hostnames, port registry, reverse-proxy routing.
+export * from "./service-hostname.js";
+export * from "./service-port-registry.js";
+export * from "./service-proxy.js";
+//# sourceMappingURL=index.js.map

package/dist/proxy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC"}

package/dist/proxy/service-hostname.d.ts

@@ -0,0 +1,21 @@
+/** Slug a hostname segment: lowercase, `[a-z0-9-]`, collapse + trim separators. */
+export declare function slugSegment(value: string): string;
+/** Build the combined leftmost label `script--branch--project` (branch omitted for main/master). */
+export declare function serviceLabel(args: {
+    script: string;
+    branch?: string | null;
+    project: string;
+}): string;
+/** Full localhost hostname for a service. */
+export declare function serviceHostname(args: {
+    script: string;
+    branch?: string | null;
+    project: string;
+}): string;
+/** Public hostname alias built from a `publicBaseUrl` (the combined label becomes the subdomain). */
+export declare function publicServiceHostname(args: {
+    script: string;
+    branch?: string | null;
+    project: string;
+}, publicBaseUrl: string): string;
+//# sourceMappingURL=service-hostname.d.ts.map

package/dist/proxy/service-hostname.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-hostname.d.ts","sourceRoot":"","sources":["../../src/proxy/service-hostname.ts"],"names":[],"mappings":"AAYA,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAOT;AAUD,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAET;AAED,qGAAqG;AACrG,wBAAgB,qBAAqB,CACnC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACjE,aAAa,EAAE,MAAM,GACpB,MAAM,CAGR"}

package/dist/proxy/service-hostname.js

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+/**
+ * Generated service hostnames (features/service-proxy.md § Generated hostname). One combined
+ * leftmost label `script--branch--project` keeps it single-level-wildcard friendly. The branch
+ * segment is omitted for main/master. Over-63-char labels are truncated with a deterministic hash
+ * suffix.
+ */
+const MAX_LABEL = 63;
+const MAIN_BRANCHES = new Set(["main", "master"]);
+/** Slug a hostname segment: lowercase, `[a-z0-9-]`, collapse + trim separators. */
+export function slugSegment(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "") || "x");
+}
+/** Build the combined leftmost label `script--branch--project` (branch omitted for main/master). */
+export function serviceLabel(args) {
+    const script = slugSegment(args.script);
+    const project = slugSegment(args.project);
+    const branch = args.branch ? slugSegment(args.branch) : "";
+    const omitBranch = !branch || MAIN_BRANCHES.has(branch);
+    const label = omitBranch ? `${script}--${project}` : `${script}--${branch}--${project}`;
+    return clampLabel(label);
+}
+/** Truncate an over-63-char label and append a deterministic 7-char hash suffix. */
+function clampLabel(label) {
+    if (label.length <= MAX_LABEL)
+        return label;
+    const hash = createHash("sha256").update(label).digest("hex").slice(0, 7);
+    const head = label.slice(0, MAX_LABEL - 8).replace(/-+$/, "");
+    return `${head}-${hash}`;
+}
+/** Full localhost hostname for a service. */
+export function serviceHostname(args) {
+    return `${serviceLabel(args)}.localhost`;
+}
+/** Public hostname alias built from a `publicBaseUrl` (the combined label becomes the subdomain). */
+export function publicServiceHostname(args, publicBaseUrl) {
+    const base = publicBaseUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    return `${serviceLabel(args)}.${base}`;
+}
+//# sourceMappingURL=service-hostname.js.map

package/dist/proxy/service-hostname.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-hostname.js","sourceRoot":"","sources":["../../src/proxy/service-hostname.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AAEH,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElD,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,CACL,KAAK;SACF,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,GAAG,CAClC,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAC,IAI5B;IACC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,MAAM,KAAK,OAAO,EAAE,CAAC;IACxF,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,oFAAoF;AACpF,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC9D,OAAO,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,eAAe,CAAC,IAI/B;IACC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC;AAC3C,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,qBAAqB,CACnC,IAAiE,EACjE,aAAqB;IAErB,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3E,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;AACzC,CAAC"}

package/dist/proxy/service-port-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * In-memory service route table + port assignments (features/service-proxy.md § Behavior, § Data).
+ * Tied to running `type:"service"` scripts; not persisted across restarts.
+ */
+export interface ServiceRoute {
+    /** Owning script/terminal slot. */
+    slot: number;
+    script: string;
+    branch?: string | null;
+    project: string;
+    port: number;
+    /** All hostnames (localhost + optional public) that map to this route. */
+    hostnames: string[];
+}
+/** Bind to port 0 to obtain a free localhost port, then release it. */
+export declare function assignFreePort(): Promise<number>;
+export declare class ServicePortRegistry {
+    private readonly publicBaseUrl?;
+    private readonly byHostname;
+    private readonly bySlot;
+    constructor(publicBaseUrl?: string | undefined);
+    /** Register a route for a started service. Returns the route (incl. generated hostnames). */
+    register(args: {
+        slot: number;
+        script: string;
+        branch?: string | null;
+        project: string;
+        port: number;
+    }): ServiceRoute;
+    /** Deregister + release a route by slot (service stop). */
+    unregister(slot: number): boolean;
+    /** Look up a route by the raw `Host` header (strips any `:port`). */
+    lookup(host: string | undefined): ServiceRoute | undefined;
+    list(): ServiceRoute[];
+}
+//# sourceMappingURL=service-port-registry.d.ts.map

package/dist/proxy/service-port-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-port-registry.d.ts","sourceRoot":"","sources":["../../src/proxy/service-port-registry.ts"],"names":[],"mappings":"AAIA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAWhD;AAED,qBAAa,mBAAmB;IAIlB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAH3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAE7B,aAAa,CAAC,EAAE,MAAM,YAAA;IAEnD,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,YAAY;IAUhB,2DAA2D;IAC3D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQjC,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS;IAM1D,IAAI,IAAI,YAAY,EAAE;CAGvB"}

package/dist/proxy/service-port-registry.js

@@ -0,0 +1,55 @@
+import { createServer } from "node:net";
+import { publicServiceHostname, serviceHostname } from "./service-hostname.js";
+/** Bind to port 0 to obtain a free localhost port, then release it. */
+export function assignFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+export class ServicePortRegistry {
+    publicBaseUrl;
+    byHostname = new Map();
+    bySlot = new Map();
+    constructor(publicBaseUrl) {
+        this.publicBaseUrl = publicBaseUrl;
+    }
+    /** Register a route for a started service. Returns the route (incl. generated hostnames). */
+    register(args) {
+        const hostnames = [serviceHostname(args)];
+        if (this.publicBaseUrl)
+            hostnames.push(publicServiceHostname(args, this.publicBaseUrl));
+        const route = { ...args, hostnames };
+        for (const hostname of hostnames)
+            this.byHostname.set(hostname.toLowerCase(), route);
+        this.bySlot.set(args.slot, route);
+        return route;
+    }
+    /** Deregister + release a route by slot (service stop). */
+    unregister(slot) {
+        const route = this.bySlot.get(slot);
+        if (!route)
+            return false;
+        for (const hostname of route.hostnames)
+            this.byHostname.delete(hostname.toLowerCase());
+        this.bySlot.delete(slot);
+        return true;
+    }
+    /** Look up a route by the raw `Host` header (strips any `:port`). */
+    lookup(host) {
+        if (!host)
+            return undefined;
+        const hostname = host.split(":")[0]?.toLowerCase() ?? "";
+        return this.byHostname.get(hostname);
+    }
+    list() {
+        return [...this.bySlot.values()];
+    }
+}
+//# sourceMappingURL=service-port-registry.js.map

package/dist/proxy/service-port-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-port-registry.js","sourceRoot":"","sources":["../../src/proxy/service-port-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAkB/E,uEAAuE;AACvE,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YACjC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,mBAAmB;IAID;IAHZ,UAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC7C,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE1D,YAA6B,aAAsB;QAAtB,kBAAa,GAAb,aAAa,CAAS;IAAG,CAAC;IAEvD,6FAA6F;IAC7F,QAAQ,CAAC,IAMR;QACC,MAAM,SAAS,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,aAAa;YAAE,SAAS,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;QAExF,MAAM,KAAK,GAAiB,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC;QACnD,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;QACrF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,UAAU,CAAC,IAAY;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS;YAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qEAAqE;IACrE,MAAM,CAAC,IAAwB;QAC7B,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/proxy/service-proxy.d.ts

@@ -0,0 +1,34 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { ServicePortRegistry } from "./service-port-registry.js";
+/**
+ * HTTP service proxy (features/service-proxy.md § Behavior; architecture/config.md
+ * `daemon.serviceProxy`). Localhost service routes are always on; the optional public alias + a
+ * separate service-only listener are gated by config. Proxied service traffic is NOT gated by daemon
+ * password auth.
+ */
+export interface ServiceProxyConfig {
+    listen?: string;
+    publicBaseUrl?: string;
+    /** `false` suppresses ONLY the optional public/listen layers; the localhost proxy stays on. */
+    enabled: boolean;
+}
+/** Resolve effective config from the persisted daemon config + env overrides (env wins). */
+export declare function resolveServiceProxyConfig(daemonServiceProxy: {
+    listen?: string;
+    publicBaseUrl?: string;
+    enabled?: boolean;
+} | undefined, env?: NodeJS.ProcessEnv): ServiceProxyConfig;
+export declare class ServiceProxy {
+    readonly registry: ServicePortRegistry;
+    private readonly config;
+    constructor(config: ServiceProxyConfig);
+    /** Optional separate service-only listener address (only when enabled + configured). */
+    get listenAddress(): string | undefined;
+    /**
+     * Try to handle a request as service traffic. Returns true when the Host matched a service route
+     * and the request was reverse-proxied; false when the caller should fall through to normal daemon
+     * handling. The `Host` header is forwarded UNCHANGED (routing depends on it).
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse): boolean;
+}
+//# sourceMappingURL=service-proxy.d.ts.map

package/dist/proxy/service-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-proxy.d.ts","sourceRoot":"","sources":["../../src/proxy/service-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAA0B,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAE9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;;;GAKG;AAEH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,4FAA4F;AAC5F,wBAAgB,yBAAyB,CACvC,kBAAkB,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,EAC9F,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,kBAAkB,CAUpB;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,EAAE,kBAAkB;IAMtC,wFAAwF;IACxF,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAEtC;IAED;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO;CAyBlE"}

package/dist/proxy/service-proxy.js

@@ -0,0 +1,54 @@
+import { request as httpRequest } from "node:http";
+import { ServicePortRegistry } from "./service-port-registry.js";
+/** Resolve effective config from the persisted daemon config + env overrides (env wins). */
+export function resolveServiceProxyConfig(daemonServiceProxy, env = process.env) {
+    const listen = env.PI_STUDIO_SERVICE_PROXY_LISTEN ?? daemonServiceProxy?.listen;
+    const publicBaseUrl = env.PI_STUDIO_SERVICE_PROXY_PUBLIC_BASE_URL ?? daemonServiceProxy?.publicBaseUrl;
+    const enabledEnv = env.PI_STUDIO_SERVICE_PROXY_ENABLED;
+    const enabled = enabledEnv !== undefined
+        ? enabledEnv === "true" || enabledEnv === "1"
+        : daemonServiceProxy?.enabled !== false;
+    return { listen, publicBaseUrl, enabled };
+}
+export class ServiceProxy {
+    registry;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Public aliases are an optional layer → only when enabled.
+        this.registry = new ServicePortRegistry(config.enabled ? config.publicBaseUrl : undefined);
+    }
+    /** Optional separate service-only listener address (only when enabled + configured). */
+    get listenAddress() {
+        return this.config.enabled ? this.config.listen : undefined;
+    }
+    /**
+     * Try to handle a request as service traffic. Returns true when the Host matched a service route
+     * and the request was reverse-proxied; false when the caller should fall through to normal daemon
+     * handling. The `Host` header is forwarded UNCHANGED (routing depends on it).
+     */
+    handleRequest(req, res) {
+        const route = this.registry.lookup(req.headers.host);
+        if (!route)
+            return false;
+        const proxyReq = httpRequest({
+            host: "127.0.0.1",
+            port: route.port,
+            method: req.method,
+            path: req.url,
+            headers: req.headers, // Host forwarded unchanged
+        }, (proxyRes) => {
+            res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+            proxyRes.pipe(res);
+        });
+        proxyReq.on("error", () => {
+            // Service not yet listening / crashed → 502 (do not crash the daemon).
+            if (!res.headersSent)
+                res.writeHead(502, { "content-type": "text/plain" });
+            res.end("service unavailable");
+        });
+        req.pipe(proxyReq);
+        return true;
+    }
+}
+//# sourceMappingURL=service-proxy.js.map

package/dist/proxy/service-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-proxy.js","sourceRoot":"","sources":["../../src/proxy/service-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,OAAO,IAAI,WAAW,EAAuB,MAAM,WAAW,CAAC;AAE9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAgBjE,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CACvC,kBAA8F,EAC9F,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,MAAM,GAAG,GAAG,CAAC,8BAA8B,IAAI,kBAAkB,EAAE,MAAM,CAAC;IAChF,MAAM,aAAa,GACjB,GAAG,CAAC,uCAAuC,IAAI,kBAAkB,EAAE,aAAa,CAAC;IACnF,MAAM,UAAU,GAAG,GAAG,CAAC,+BAA+B,CAAC;IACvD,MAAM,OAAO,GACX,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,GAAG;QAC7C,CAAC,CAAC,kBAAkB,EAAE,OAAO,KAAK,KAAK,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,OAAO,YAAY;IACd,QAAQ,CAAsB;IACtB,MAAM,CAAqB;IAE5C,YAAY,MAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,4DAA4D;QAC5D,IAAI,CAAC,QAAQ,GAAG,IAAI,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC7F,CAAC;IAED,wFAAwF;IACxF,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,GAAoB,EAAE,GAAmB;QACrD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAEzB,MAAM,QAAQ,GAAG,WAAW,CAC1B;YACE,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,IAAI,EAAE,GAAG,CAAC,GAAG;YACb,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,2BAA2B;SAClD,EACD,CAAC,QAAQ,EAAE,EAAE;YACX,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC,CACF,CAAC;QACF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,uEAAuE;YACvE,IAAI,CAAC,GAAG,CAAC,WAAW;gBAAE,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC;YAC3E,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/terminal/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./pty-backend.js";
+export * from "./terminal-manager.js";
+export * from "./terminal-rpc.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/terminal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AACA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/terminal/index.js

@@ -0,0 +1,5 @@
+// PTY terminal manager + backend abstraction (binary terminal stream).
+export * from "./pty-backend.js";
+export * from "./terminal-manager.js";
+export * from "./terminal-rpc.js";
+//# sourceMappingURL=index.js.map

package/dist/terminal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/terminal/pty-backend.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PTY backend abstraction (features/terminals.md § Behavior). The production backend is `node-pty`,
+ * which gives a **real TTY** (programs see `isatty`, get SIGWINCH on resize, and run full-screen
+ * apps like vim/htop correctly). A piped-`child_process` fallback remains for environments where the
+ * native module is unavailable and for deterministic tests (which inject their own fake backend).
+ */
+export interface PtyProcess {
+    write(data: Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    onData(cb: (data: Uint8Array) => void): void;
+    onExit(cb: (code: number | null) => void): void;
+}
+export interface PtySpawnOptions {
+    shell: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols: number;
+    rows: number;
+}
+export interface PtyBackend {
+    spawn(opts: PtySpawnOptions): PtyProcess;
+}
+/**
+ * Resolve a shell/binary name to an absolute path via `$PATH` (cross-platform, honors Windows
+ * PATHEXT). Returns the input unchanged when it already looks like a path or cannot be resolved
+ * (the spawn will then surface a clear ENOENT).
+ */
+export declare function resolveExecutable(bin: string, env?: Record<string, string | undefined>): string;
+/** Production backend: a real PTY via `node-pty`. */
+export declare class NodePtyBackend implements PtyBackend {
+    spawn(opts: PtySpawnOptions): PtyProcess;
+}
+/** Fallback backend: a piped child process. Not a real TTY, but streams stdout/stderr ⇄ stdin. */
+export declare class ChildProcessPtyBackend implements PtyBackend {
+    spawn(opts: PtySpawnOptions): PtyProcess;
+}
+/**
+ * Default backend factory: prefer the real PTY (`node-pty`); if the native module cannot be loaded
+ * on this platform, fall back to the piped child-process backend.
+ */
+export declare function createDefaultPtyBackend(): PtyBackend;
+//# sourceMappingURL=pty-backend.d.ts.map

package/dist/terminal/pty-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-backend.d.ts","sourceRoot":"","sources":["../../src/terminal/pty-backend.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7C,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CAAC;CAC1C;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAIR;AAUD,qDAAqD;AACrD,qBAAa,cAAe,YAAW,UAAU;IAC/C,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU;CAmCzC;AAED,kGAAkG;AAClG,qBAAa,sBAAuB,YAAW,UAAU;IACvD,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU;CA2CzC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,CAQpD"}