feat: let agents start new sessions via spawn_session tool

Add a project-scoped spawn_session tool so agents can dispatch new,
independent sessions (ralph loops, long-plan chaining). Spawned sessions
are constrained to a workspace/worktree of the same registered project,
appear in the session list immediately via a new session.created event,
and the capability is on by default with a Settings -> Session daemon
toggle (spawnSessions / PI_WEB_SPAWN_SESSIONS).

Note: adds a session daemon code path, so pi-web-sessiond.service must be
restarted manually for the server side to take effect.

src/client/src/api/parsers.test.ts

@@ -9,13 +9,13 @@ describe("API parsers", () => {
       exists: true,
       config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } } },
       effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true },
-      envOverrides: { host: true, port: false, allowedHosts: false },
+      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false },
     })).toEqual({
       path: "/tmp/config.json",
       exists: true,
       config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } } },
       effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true },
-      envOverrides: { host: true, port: false, allowedHosts: false },
+      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false },
     });
   });
 

src/client/src/api/parsers.ts

@@ -445,6 +445,7 @@ function parsePiWebConfigValues(value: unknown): PiWebConfigValues {
     ...optionalField("allowedHosts", optionalAllowedHosts(record["allowedHosts"])),
     ...optionalField("shortcuts", optionalShortcuts(record["shortcuts"])),
     ...optionalField("plugins", optionalPlugins(record["plugins"])),
+    ...optionalField("spawnSessions", optionalBoolean(record, "spawnSessions")),
   };
 }
 
@@ -479,7 +480,7 @@ function optionalPlugins(value: unknown): PiWebPluginConfigMap | undefined {
 
 function parsePiWebConfigEnvOverrides(value: unknown): PiWebConfigEnvOverrides {
   const record = requireRecord(value);
-  return { host: requireBoolean(record, "host"), port: requireBoolean(record, "port"), allowedHosts: requireBoolean(record, "allowedHosts") };
+  return { host: requireBoolean(record, "host"), port: requireBoolean(record, "port"), allowedHosts: requireBoolean(record, "allowedHosts"), spawnSessions: requireBoolean(record, "spawnSessions") };
 }
 
 export function parsePiWebPluginsResponse(value: unknown): PiWebPluginsResponse {
@@ -723,6 +724,13 @@ export function parseReloaded(value: unknown): { reloaded: true } {
   return { reloaded: true };
 }
 
+function optionalBoolean(record: Record<string, unknown>, key: string): boolean | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`Invalid PI WEB ${key} field`);
+  return value;
+}
+
 function optionalNumber(record: Record<string, unknown>, key: string): number | undefined {
   const value = record[key];
   if (value === undefined) return undefined;

src/client/src/components/SettingsDialog.ts

@@ -4,6 +4,7 @@ import type { AppAction } from "../actions";
 import { configApi, pluginsApi, type PiWebConfigResponse, type PiWebConfigValues, type PiWebPluginsResponse } from "../api";
 import type { SettingsSection } from "../settingsRoute";
 import "./settings/SettingsGeneralPanel";
+import "./settings/SettingsSessiondPanel";
 import "./settings/SettingsPluginsPanel";
 import "./settings/SettingsShortcutsPanel";
 
@@ -47,6 +48,7 @@ export class SettingsDialog extends LitElement {
           <div class="settings-body">
             <nav class="settings-nav" aria-label="Settings sections">
               ${this.renderNavButton("general", "General", "Server config")}
+              ${this.renderNavButton("sessiond", "Session daemon", "Runtime settings")}
               ${this.renderNavButton("plugins", "Plugins", "Enable and disable")}
               ${this.renderNavButton("shortcuts", "Keyboard", "Shortcuts")}
             </nav>
@@ -60,6 +62,19 @@ export class SettingsDialog extends LitElement {
   }
 
   private renderActiveSection(): TemplateResult {
+    if (this.section === "sessiond") {
+      return html`
+        <settings-sessiond-panel
+          .configResponse=${this.configResponse}
+          .loading=${this.loading}
+          .saving=${this.saving}
+          .error=${this.error}
+          .savedMessage=${this.savedMessage}
+          .onReload=${() => this.loadConfig()}
+          .onSave=${(config: PiWebConfigValues) => this.saveConfig(config)}
+        ></settings-sessiond-panel>
+      `;
+    }
     if (this.section === "shortcuts") {
       return html`
         <settings-shortcuts-panel

src/client/src/components/settings/SettingsSessiondPanel.ts

@@ -0,0 +1,114 @@
+import { css, html, LitElement, type TemplateResult } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import type { PiWebConfigResponse, PiWebConfigValues } from "../../api";
+
+@customElement("settings-sessiond-panel")
+export class SettingsSessiondPanel extends LitElement {
+  @property({ attribute: false }) configResponse: PiWebConfigResponse | undefined;
+  @property({ type: Boolean }) loading = false;
+  @property({ type: Boolean }) saving = false;
+  @property() error = "";
+  @property() savedMessage = "";
+  @property({ attribute: false }) onReload?: () => void | Promise<void>;
+  @property({ attribute: false }) onSave?: (config: PiWebConfigValues) => void | Promise<void>;
+
+  override render(): TemplateResult {
+    const config = this.configResponse;
+    const spawnOverridden = config?.envOverrides.spawnSessions === true;
+    // On by default: the effective config is the source of truth for the toggle
+    // state, so an unset config file still shows the feature as enabled.
+    const effectiveSpawn = config?.effectiveConfig.spawnSessions !== false;
+    return html`
+      <div class="section-heading">
+        <div>
+          <h2>Session daemon</h2>
+          <p>These settings affect the long-lived session runtime. Changes are saved to the config file immediately but only take effect after the session daemon restarts.</p>
+        </div>
+        <button class="secondary" ?disabled=${this.loading} @click=${() => { void this.onReload?.(); }}>Reload</button>
+      </div>
+      ${this.renderMessages()}
+      <div class="restart-note" role="note">Restart required: run <code>pi-web restart</code> (or restart the session daemon service) after changing these settings.</div>
+      ${config === undefined && this.loading ? html`<div class="loading-card">Loading configuration…</div>` : html`
+        <div class="config-path-card">
+          <span>Config file</span>
+          <code>${config?.path ?? "Unknown"}</code>
+        </div>
+        <div class="field">
+          <span class="field-heading">
+            <span>Allow agents to start sessions</span>
+            ${spawnOverridden ? html`<span class="override-badge">environment override</span>` : null}
+          </span>
+          <label class="toggle">
+            <input
+              type="checkbox"
+              .checked=${effectiveSpawn}
+              ?disabled=${this.loading || this.saving || spawnOverridden}
+              @change=${(event: Event) => { void this.toggleSpawnSessions(event); }}
+            >
+            <span>Enable the <code>spawn_session</code> tool</span>
+          </label>
+          <small>When enabled, LLMs can start new sessions, constrained to a workspace (any worktree) of the same registered project so every spawned session stays visible here. On by default.</small>
+        </div>
+        <section class="effective-card" aria-label="Effective configuration summary">
+          <h3>Effective after environment overrides</h3>
+          <dl>
+            <div><dt>Spawn sessions</dt><dd>${effectiveSpawn ? "Enabled" : html`<span class="muted">Disabled</span>`}</dd></div>
+          </dl>
+        </section>
+      `}
+    `;
+  }
+
+  private renderMessages(): TemplateResult | null {
+    if (this.error !== "") return html`<div class="message error-message">${this.error}</div>`;
+    if (this.savedMessage !== "") return html`<div class="message success-message">${this.savedMessage}</div>`;
+    return null;
+  }
+
+  private async toggleSpawnSessions(event: Event): Promise<void> {
+    const enabled = event.target instanceof HTMLInputElement && event.target.checked;
+    const baseConfig = this.configResponse?.config ?? {};
+    await this.onSave?.({ ...baseConfig, spawnSessions: enabled });
+  }
+
+  static override styles = css`
+    :host { display: block; }
+    .section-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; margin-bottom: 14px; }
+    .section-heading > div { display: grid; gap: 6px; min-width: 0; }
+    h2, h3, p { margin: 0; }
+    h2 { font-size: 17px; line-height: 1.25; }
+    h3 { font-size: 13px; line-height: 1.3; }
+    p { color: var(--pi-muted); line-height: 1.45; }
+    button, input { font: inherit; }
+    button { border: 1px solid var(--pi-border); border-radius: 8px; background: var(--pi-surface); color: var(--pi-text); padding: 7px 9px; cursor: pointer; }
+    button:disabled { opacity: .55; cursor: not-allowed; }
+    .secondary { flex: 0 0 auto; }
+    .message, .loading-card, .config-path-card, .effective-card, .restart-note { border: 1px solid var(--pi-border); border-radius: 10px; background: var(--pi-surface); padding: 12px; }
+    .message { margin-bottom: 12px; }
+    .error-message { border-color: var(--pi-danger); color: var(--pi-danger); background: color-mix(in srgb, var(--pi-danger) 10%, var(--pi-surface)); }
+    .success-message { border-color: var(--pi-success-border); color: var(--pi-success); background: var(--pi-success-surface); }
+    .loading-card { color: var(--pi-muted); }
+    .restart-note { margin-bottom: 14px; border-color: var(--pi-warning-border); color: var(--pi-warning); background: var(--pi-warning-surface); line-height: 1.45; }
+    .config-path-card { display: grid; gap: 5px; margin-bottom: 14px; }
+    .config-path-card span, .field-heading, dt { color: var(--pi-muted); font-size: 12px; font-weight: 700; text-transform: uppercase; }
+    code { border: 1px solid var(--pi-border-muted); border-radius: 5px; background: var(--pi-bg); padding: 1px 4px; color: var(--pi-text); font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; overflow-wrap: anywhere; }
+    .field { display: grid; gap: 7px; margin-bottom: 14px; }
+    .field small { color: var(--pi-muted); line-height: 1.45; }
+    .field-heading { display: flex; align-items: center; gap: 8px; }
+    .toggle { display: flex; align-items: center; gap: 9px; cursor: pointer; }
+    .toggle input { width: 16px; height: 16px; }
+    .toggle input:disabled { cursor: not-allowed; }
+    .override-badge { border: 1px solid var(--pi-warning-border); border-radius: 999px; color: var(--pi-warning); background: var(--pi-warning-surface); padding: 2px 7px; font-size: 11px; font-weight: 600; text-transform: none; }
+    .effective-card { display: grid; gap: 10px; }
+    .effective-card dl { display: grid; gap: 8px; margin: 0; }
+    .effective-card dl > div { display: grid; grid-template-columns: 130px minmax(0, 1fr); gap: 12px; align-items: baseline; }
+    dd { margin: 0; min-width: 0; overflow-wrap: anywhere; }
+    .muted { color: var(--pi-muted); }
+
+    @media (max-width: 760px) {
+      .section-heading { display: grid; gap: 12px; }
+      .section-heading .secondary { justify-self: start; }
+      .effective-card dl > div { grid-template-columns: minmax(0, 1fr); gap: 3px; }
+    }
+  `;
+}

src/client/src/components/settings/settingsConfigDraft.test.ts

@@ -26,4 +26,14 @@ describe("settings config drafts", () => {
       plugins: { info: { enabled: false } },
     });
   });
+
+  it("preserves the spawnSessions flag when saving general settings", () => {
+    const result = configFromDraft({
+      host: "",
+      port: "",
+      allowedHostsMode: "list",
+      allowedHostsText: "",
+    }, { spawnSessions: true });
+    expect(result.spawnSessions).toBe(true);
+  });
 });

src/client/src/components/settings/settingsConfigDraft.ts

@@ -24,6 +24,7 @@ export function configFromDraft(draft: ConfigDraft, baseConfig: PiWebConfigValue
   const config: PiWebConfigValues = {
     ...(baseConfig.shortcuts === undefined ? {} : { shortcuts: baseConfig.shortcuts }),
     ...(baseConfig.plugins === undefined ? {} : { plugins: baseConfig.plugins }),
+    ...(baseConfig.spawnSessions === undefined ? {} : { spawnSessions: baseConfig.spawnSessions }),
   };
   const host = draft.host.trim();
   const port = draft.port.trim();

src/client/src/controllers/sessionController.test.ts

@@ -142,6 +142,38 @@ describe("SessionController", () => {
     expect(state.selectedSession?.messageCount).toBe(3);
   });
 
+  it("adds a newly created session to the list when it belongs to the selected workspace", () => {
+    let state: AppState = { ...initialAppState(), selectedWorkspace: workspace, sessions: [oldSession] };
+    const controller = new SessionController(
+      () => state,
+      (patch) => { state = { ...state, ...patch }; },
+      () => undefined,
+      undefined,
+      { socket: new FakeSocket() },
+    );
+    const spawned: SessionInfo = { ...oldSession, id: "spawned-session", path: "/tmp/spawned-session.jsonl" };
+
+    controller.applyGlobalEvent({ type: "session.created", session: spawned });
+
+    expect(state.sessions.map((session) => session.id)).toEqual(["spawned-session", "old-session"]);
+  });
+
+  it("ignores a created session for a different workspace or a duplicate id", () => {
+    let state: AppState = { ...initialAppState(), selectedWorkspace: workspace, sessions: [oldSession] };
+    const controller = new SessionController(
+      () => state,
+      (patch) => { state = { ...state, ...patch }; },
+      () => undefined,
+      undefined,
+      { socket: new FakeSocket() },
+    );
+
+    controller.applyGlobalEvent({ type: "session.created", session: { ...oldSession, id: "other", cwd: "/other-repo" } });
+    controller.applyGlobalEvent({ type: "session.created", session: { ...oldSession } });
+
+    expect(state.sessions.map((session) => session.id)).toEqual(["old-session"]);
+  });
+
   it("toggles the per-session sending state around an inline attachment send and forwards attachments", async () => {
     let resolvePrompt: (() => void) | undefined;
     let promptArgs: { attachments?: PromptAttachment[] } | undefined;

src/client/src/controllers/sessionController.ts

@@ -51,6 +51,7 @@ export class SessionController {
   applyGlobalEvent(event: GlobalSessionEvent): void {
     if (event.type === "status.update") this.applyStatus(event.status);
     else if (event.type === "activity.update") this.applyActivity(event.activity);
+    else if (event.type === "session.created") this.applyCreatedSession(event.session);
     else this.applySessionName(event.sessionId, event.name);
   }
 
@@ -576,6 +577,16 @@ export class SessionController {
     }
   }
 
+  private applyCreatedSession(session: SessionInfo) {
+    const state = this.getState();
+    // Only surface sessions for the workspace currently in view; others are
+    // picked up when their workspace is opened. Skip if already present (e.g.
+    // the optimistic insert from startSession in this same tab).
+    if (state.selectedWorkspace?.path !== session.cwd) return;
+    if (state.sessions.some((candidate) => candidate.id === session.id)) return;
+    this.setState({ sessions: [session, ...state.sessions] });
+  }
+
   private applyActivity(activity: SessionActivity) {
     this.setState({
       sessionActivities: { ...this.getState().sessionActivities, [activity.sessionId]: activity },

src/client/src/sessionSocket.ts

@@ -131,12 +131,12 @@ export class RealtimeSocket {
 
 function isSessionUiEvent(event: unknown): event is SessionUiEvent {
   const type = eventType(event);
-  return ["message.append", "assistant.delta", "assistant.thinking.delta", "tool.start", "tool.update", "tool.end", "shell.start", "shell.chunk", "shell.end", "agent.start", "agent.end", "message.end", "status.update", "activity.update", "command.output", "session.error", "session.name", "pi.event"].includes(type);
+  return ["message.append", "assistant.delta", "assistant.thinking.delta", "tool.start", "tool.update", "tool.end", "shell.start", "shell.chunk", "shell.end", "agent.start", "agent.end", "message.end", "status.update", "activity.update", "command.output", "session.error", "session.name", "session.created", "pi.event"].includes(type);
 }
 
 function isGlobalSessionEvent(event: unknown): event is GlobalSessionEvent {
   const type = eventType(event);
-  return type === "status.update" || type === "activity.update" || type === "session.name";
+  return type === "status.update" || type === "activity.update" || type === "session.name" || type === "session.created";
 }
 
 function isRealtimeEvent(event: unknown): event is RealtimeEvent {

src/client/src/settingsRoute.test.ts

@@ -35,6 +35,8 @@ function installWindow(href: string): { pushed: string[]; replaced: string[] } {
 describe("settings route helpers", () => {
   it("parses supported settings deep links and aliases", () => {
     expect(parseSettingsSection("general")).toBe("general");
+    expect(parseSettingsSection("sessiond")).toBe("sessiond");
+    expect(parseSettingsSection("sessions")).toBe("sessiond");
     expect(parseSettingsSection("plugins")).toBe("plugins");
     expect(parseSettingsSection("shortcuts")).toBe("shortcuts");
     expect(parseSettingsSection("keyboard")).toBe("shortcuts");

src/client/src/settingsRoute.ts

@@ -1,4 +1,4 @@
-export type SettingsSection = "general" | "plugins" | "shortcuts";
+export type SettingsSection = "general" | "sessiond" | "plugins" | "shortcuts";
 
 export function readSettingsSection(): SettingsSection | undefined {
   return parseSettingsSection(new URLSearchParams(window.location.search).get("settings"));
@@ -17,6 +17,7 @@ export function writeSettingsSection(section: SettingsSection | undefined, optio
 
 export function parseSettingsSection(value: string | null): SettingsSection | undefined {
   if (value === "general") return "general";
+  if (value === "sessiond" || value === "sessions") return "sessiond";
   if (value === "plugins") return "plugins";
   if (value === "shortcuts" || value === "keyboard" || value === "keyboard-shortcuts") return "shortcuts";
   return undefined;