@jhytabest/plashboard 0.1.11 → 1.0.1

package/README.md

@@ -23,7 +23,9 @@ openclaw plugins update plashboard
 
 No manual config is required for first use. Defaults are safe:
 - `fill_provider=openclaw`
+- `allow_command_fill=false`
 - `openclaw_fill_agent_id=main`
+- `session_strategy=persistent`
 - automatic init on service start
 - automatic starter template seed when template store is empty
 
@@ -55,7 +57,9 @@ Add to `openclaw.json`:
           "session_timeout_seconds": 90,
           "auto_seed_template": true,
           "fill_provider": "openclaw",
+          "allow_command_fill": false,
           "openclaw_fill_agent_id": "main",
+          "session_strategy": "persistent",
           "display_profile": {
             "width_px": 1920,
             "height_px": 1080,
@@ -72,7 +76,47 @@ Add to `openclaw.json`:
 ```
 
 `fill_provider: "openclaw"` is the default real mode and calls `openclaw agent` directly.
-Use `fill_provider: "command"` only if you need a custom external runner.
+`fill_provider: "command"` requires explicit opt-in with `allow_command_fill: true`.
+Use command mode only if you need a custom external runner.
+
+`session_strategy` controls OpenClaw session reuse for fills:
+- `persistent` (default): reuses the agent's normal long-lived session behavior.
+- `ephemeral`: each fill run gets a unique `--session-id`; after the run, plugin performs best-effort cleanup via official CLI API: `openclaw sessions delete --agent <id> --session-id <id>`.
+
+Tradeoffs:
+- `persistent` keeps conversational memory/context between runs.
+- `ephemeral` isolates runs and avoids long-lived context drift, but loses cross-run memory and adds one cleanup CLI call per run.
+
+Example ephemeral config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "plashboard": {
+        "enabled": true,
+        "config": {
+          "fill_provider": "openclaw",
+          "openclaw_fill_agent_id": "plashboard-fill",
+          "session_strategy": "ephemeral"
+        }
+      }
+    }
+  }
+}
+```
+
+For production stability, use a dedicated fill agent instead of `main`:
+
+```bash
+openclaw agents add plashboard-fill --non-interactive --workspace /var/lib/openclaw/.openclaw/workspace-plashboard-fill
+```
+
+Then run:
+
+```text
+/plashboard setup openclaw plashboard-fill
+```
 
 ## Runtime Command
 
@@ -81,6 +125,7 @@ Use `fill_provider: "command"` only if you need a custom external runner.
 /plashboard setup [openclaw [agent_id]|mock|command <fill_command>]
 /plashboard quickstart <description>
 /plashboard doctor [local_url] [https_port] [repo_dir]
+/plashboard fix-permissions [dashboard_output_path]
 /plashboard web-guide [local_url] [repo_dir]
 /plashboard expose-guide [local_url] [https_port]
 /plashboard expose-check [local_url] [https_port]
@@ -100,12 +145,21 @@ Recommended first run:
 /plashboard onboard "Focus on service health, priorities, blockers, and next actions."
 ```
 
+For command mode, explicit opt-in is required:
+
+```text
+/plashboard setup command <fill_command>
+```
+
+This command writes `allow_command_fill=true` with `fill_provider=command`.
+
 If `onboard` returns web/exposure warnings:
 
 ```text
 /plashboard web-guide
 /plashboard expose-guide
 /plashboard doctor
+/plashboard fix-permissions
 ```
 
 Tailscale helper flow:
@@ -119,3 +173,5 @@ Tailscale helper flow:
 
 - The plugin includes an admin skill (`plashboard-admin`) for tool-guided management.
 - Trusted publishing (OIDC) is enabled in CI/CD for npm releases.
+- If you see `plugins.allow is empty`, add explicit trust list in OpenClaw config:
+  - `"plugins": { "allow": ["plashboard"] }`

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "plashboard",
   "name": "Plashboard",
-  "version": "0.1.11",
+  "version": "1.0.0",
   "description": "Template-driven dashboard runtime with scheduled OpenClaw fills and safe publish.",
   "entry": "./src/index.ts",
   "skills": ["./skills/plashboard-admin"],
@@ -17,8 +17,10 @@
       "session_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 600, "default": 90 },
       "auto_seed_template": { "type": "boolean", "default": true },
       "fill_provider": { "type": "string", "enum": ["command", "mock", "openclaw"], "default": "openclaw" },
+      "allow_command_fill": { "type": "boolean", "default": false },
       "fill_command": { "type": "string" },
       "openclaw_fill_agent_id": { "type": "string", "default": "main" },
+      "session_strategy": { "type": "string", "enum": ["persistent", "ephemeral"], "default": "persistent" },
       "python_bin": { "type": "string", "default": "python3" },
       "writer_script_path": { "type": "string" },
       "dashboard_output_path": { "type": "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhytabest/plashboard",
-  "version": "0.1.11",
+  "version": "1.0.1",
   "private": false,
   "description": "Plashboard OpenClaw plugin runtime",
   "license": "MIT",
@@ -17,7 +17,7 @@
   "files": [
     "openclaw.plugin.json",
     "schema",
-    "scripts",
+    "scripts/dashboard_write.py",
     "skills",
     "src",
     "tsconfig.json",
@@ -27,6 +27,7 @@
     "access": "public"
   },
   "scripts": {
+    "security:scan": "node ./dev-security-scan.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"

package/skills/plashboard-admin/SKILL.md

@@ -24,6 +24,7 @@ Always use plugin tools:
 - `plashboard_exposure_check`
 - `plashboard_web_guide`
 - `plashboard_doctor`
+- `plashboard_permissions_fix`
 - `plashboard_init`
 - `plashboard_quickstart`
 - `plashboard_template_create`
@@ -59,6 +60,7 @@ Always use plugin tools:
 - `/plashboard quickstart <description>`
 - `/plashboard setup [openclaw [agent_id]|mock|command <fill_command>]`
 - `/plashboard doctor [local_url] [https_port] [repo_dir]`
+- `/plashboard fix-permissions [dashboard_output_path]`
 - `/plashboard web-guide [local_url] [repo_dir]`
 - `/plashboard expose-guide [local_url] [https_port]`
 - `/plashboard expose-check [local_url] [https_port]`

package/src/command-runner.ts

@@ -0,0 +1,120 @@
+type CommandRunnerOptions = {
+  timeoutMs: number;
+  cwd?: string;
+  input?: string;
+  env?: Record<string, string>;
+  windowsVerbatimArguments?: boolean;
+  noOutputTimeoutMs?: number;
+};
+
+export type CommandRunResult = {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: 'exit' | 'timeout' | 'signal' | string;
+};
+
+export type CommandRunner = (
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions
+) => Promise<CommandRunResult>;
+
+export type RuntimeCommandWithTimeout = (
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions
+) => Promise<{
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: string;
+}>;
+
+export type CommandExecResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: string;
+  error?: string;
+};
+
+function asErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === 'string' && error.trim()) return error;
+  return 'unknown error';
+}
+
+export function createRuntimeCommandRunner(runtimeCommand?: RuntimeCommandWithTimeout): CommandRunner | null {
+  if (!runtimeCommand) return null;
+  return async (argv: string[], optionsOrTimeout: number | CommandRunnerOptions): Promise<CommandRunResult> => {
+    const result = await runtimeCommand(argv, optionsOrTimeout);
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      code: result.code,
+      signal: result.signal,
+      killed: result.killed,
+      termination: result.termination
+    };
+  };
+}
+
+export async function runCommand(
+  commandRunner: CommandRunner | null | undefined,
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions,
+  label: string
+): Promise<CommandExecResult> {
+  if (!commandRunner) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: '',
+      code: null,
+      error: `${label} is unavailable: OpenClaw runtime command runner is not available`
+    };
+  }
+
+  try {
+    const result = await commandRunner(argv, optionsOrTimeout);
+    return {
+      ok: result.code === 0,
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+      code: result.code,
+      signal: result.signal,
+      killed: result.killed,
+      termination: result.termination
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: '',
+      code: null,
+      error: `${label} failed: ${asErrorMessage(error)}`
+    };
+  }
+}
+
+export async function runAndReadStdout(
+  commandRunner: CommandRunner | null | undefined,
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions,
+  label: string
+): Promise<string> {
+  const result = await runCommand(commandRunner, argv, optionsOrTimeout, label);
+  if (!result.ok) {
+    const reason = result.error || result.stderr || result.stdout || result.termination || `exit=${String(result.code)}`;
+    throw new Error(`${label} failed: ${reason}`);
+  }
+  return result.stdout.trim();
+}
+
+export type { CommandRunnerOptions };

package/src/config.ts

@@ -38,6 +38,10 @@ function asObject(value: unknown): Record<string, unknown> {
     : {};
 }
 
+function asSessionStrategy(value: unknown): PlashboardConfig['session_strategy'] {
+  return value === 'ephemeral' ? 'ephemeral' : 'persistent';
+}
+
 function resolveDisplayProfile(raw: unknown): DisplayProfile {
   const data = asObject(raw);
   return {
@@ -77,8 +81,10 @@ export function resolveConfig(api: unknown): PlashboardConfig {
     session_timeout_seconds: Math.max(10, Math.floor(asNumber(raw.session_timeout_seconds, 90))),
     auto_seed_template: asBoolean(raw.auto_seed_template, true),
     fill_provider: fillProvider,
+    allow_command_fill: asBoolean(raw.allow_command_fill, false),
     fill_command: typeof raw.fill_command === 'string' ? raw.fill_command : undefined,
     openclaw_fill_agent_id: asString(raw.openclaw_fill_agent_id, 'main'),
+    session_strategy: asSessionStrategy(raw.session_strategy),
     python_bin: asString(raw.python_bin, 'python3'),
     writer_script_path: asString(raw.writer_script_path, DEFAULT_WRITER_PATH),
     dashboard_output_path: outputPath,

package/src/fill-runner.test.ts

@@ -39,8 +39,10 @@ function config(overrides: Partial<PlashboardConfig>): PlashboardConfig {
     session_timeout_seconds: 30,
     auto_seed_template: false,
     fill_provider: 'mock',
+    allow_command_fill: false,
     fill_command: undefined,
     openclaw_fill_agent_id: 'main',
+    session_strategy: 'persistent',
     python_bin: 'python3',
     writer_script_path: '/tmp/writer.py',
     dashboard_output_path: '/tmp/dashboard.json',
@@ -67,7 +69,7 @@ function context(): FillRunContext {
 }
 
 describe('createFillRunner', () => {
-  it('parses openclaw json envelope output', async () => {
+  it('persistent mode keeps standard openclaw agent session behavior', async () => {
     const commandRunner = vi.fn(async (_argv: string[], _options: unknown) => ({
       stdout: JSON.stringify({
         result: {
@@ -95,6 +97,108 @@ describe('createFillRunner', () => {
     expect(argv.slice(0, 2)).toEqual(['openclaw', 'agent']);
     expect(argv).toContain('--agent');
     expect(argv).toContain('ops');
+    expect(argv).not.toContain('--session-id');
+  });
+
+  it('ephemeral mode uses unique session ids and official cleanup command', async () => {
+    const calls: string[][] = [];
+    const commandRunner = vi.fn(async (argv: string[], _options: unknown) => {
+      calls.push(argv);
+      if (argv[0] === 'openclaw' && argv[1] === 'agent') {
+        return {
+          stdout: '{"values":{"summary":"new summary"}}',
+          stderr: '',
+          code: 0
+        };
+      }
+      if (argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete') {
+        return {
+          stdout: '{"ok":true}',
+          stderr: '',
+          code: 0
+        };
+      }
+      return {
+        stdout: '',
+        stderr: `unsupported command: ${argv.join(' ')}`,
+        code: 1
+      };
+    });
+
+    const runner = createFillRunner(
+      config({
+        fill_provider: 'openclaw',
+        openclaw_fill_agent_id: 'ops',
+        session_strategy: 'ephemeral'
+      }),
+      { commandRunner }
+    );
+
+    await runner.run(context());
+    await runner.run(context());
+
+    const agentCalls = calls.filter((argv) => argv[0] === 'openclaw' && argv[1] === 'agent');
+    const cleanupCalls = calls.filter((argv) => argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete');
+
+    expect(agentCalls).toHaveLength(2);
+    expect(cleanupCalls).toHaveLength(2);
+
+    const firstSessionFlagIndex = agentCalls[0].indexOf('--session-id');
+    const secondSessionFlagIndex = agentCalls[1].indexOf('--session-id');
+    expect(firstSessionFlagIndex).toBeGreaterThan(-1);
+    expect(secondSessionFlagIndex).toBeGreaterThan(-1);
+    const firstSessionId = agentCalls[0][firstSessionFlagIndex + 1];
+    const secondSessionId = agentCalls[1][secondSessionFlagIndex + 1];
+    expect(firstSessionId).toBeTruthy();
+    expect(secondSessionId).toBeTruthy();
+    expect(firstSessionId).not.toBe(secondSessionId);
+
+    for (const [index, cleanupCall] of cleanupCalls.entries()) {
+      expect(cleanupCall.slice(0, 3)).toEqual(['openclaw', 'sessions', 'delete']);
+      expect(cleanupCall).toContain('--agent');
+      expect(cleanupCall).toContain('ops');
+      const cleanupSessionFlagIndex = cleanupCall.indexOf('--session-id');
+      expect(cleanupSessionFlagIndex).toBeGreaterThan(-1);
+      expect(cleanupCall[cleanupSessionFlagIndex + 1]).toBe(index === 0 ? firstSessionId : secondSessionId);
+    }
+  });
+
+  it('ephemeral cleanup failure is safe and does not fail fill output', async () => {
+    const commandRunner = vi.fn(async (argv: string[], _options: unknown) => {
+      if (argv[0] === 'openclaw' && argv[1] === 'agent') {
+        return {
+          stdout: '{"values":{"summary":"new summary"}}',
+          stderr: '',
+          code: 0
+        };
+      }
+      if (argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete') {
+        return {
+          stdout: '',
+          stderr: 'session cleanup failed',
+          code: 1
+        };
+      }
+      return {
+        stdout: '',
+        stderr: `unsupported command: ${argv.join(' ')}`,
+        code: 1
+      };
+    });
+
+    const runner = createFillRunner(
+      config({
+        fill_provider: 'openclaw',
+        openclaw_fill_agent_id: 'ops',
+        session_strategy: 'ephemeral'
+      }),
+      { commandRunner }
+    );
+    const response = await runner.run(context());
+
+    expect(response.values.summary).toBe('new summary');
+    expect(commandRunner).toHaveBeenCalledTimes(2);
+    expect(commandRunner.mock.calls[1][0].slice(0, 3)).toEqual(['openclaw', 'sessions', 'delete']);
   });
 
   it('parses command runner fenced json output', async () => {
@@ -105,7 +209,7 @@ describe('createFillRunner', () => {
     }));
 
     const runner = createFillRunner(
-      config({ fill_provider: 'command', fill_command: 'echo "$PLASHBOARD_PROMPT_JSON"' }),
+      config({ fill_provider: 'command', allow_command_fill: true, fill_command: 'echo "$PLASHBOARD_PROMPT_JSON"' }),
       { commandRunner }
     );
     const response = await runner.run(context());
@@ -118,4 +222,20 @@ describe('createFillRunner', () => {
     const options = firstCall[1] as { env?: Record<string, string> };
     expect(options.env?.PLASHBOARD_PROMPT_JSON).toContain('"template"');
   });
+
+  it('rejects command fill when allow_command_fill is false', async () => {
+    const commandRunner = vi.fn(async () => ({
+      stdout: '{"values":{"summary":"from command"}}',
+      stderr: '',
+      code: 0
+    }));
+
+    const runner = createFillRunner(
+      config({ fill_provider: 'command', allow_command_fill: false, fill_command: 'echo hello' }),
+      { commandRunner }
+    );
+
+    await expect(runner.run(context())).rejects.toThrow(/allow_command_fill=true/);
+    expect(commandRunner).not.toHaveBeenCalled();
+  });
 });

package/src/fill-runner.ts

@@ -1,30 +1,12 @@
-import { spawn } from 'node:child_process';
+import { runAndReadStdout, runCommand, type CommandRunner } from './command-runner.js';
 import type { FillResponse, FillRunContext, FillRunner, PlashboardConfig } from './types.js';
 
-type CommandOptions = {
-  timeoutMs: number;
-  env?: NodeJS.ProcessEnv;
-  input?: string;
-};
-
-export type CommandRunResult = {
-  stdout: string;
-  stderr: string;
-  code: number | null;
-  signal?: NodeJS.Signals | null;
-  killed?: boolean;
-  termination?: 'exit' | 'timeout' | 'signal' | string;
-};
-
-export type CommandRunner = (
-  argv: string[],
-  optionsOrTimeout: number | CommandOptions
-) => Promise<CommandRunResult>;
-
 export interface FillRunnerDeps {
-  commandRunner?: CommandRunner;
+  commandRunner?: CommandRunner | null;
 }
 
+let ephemeralSessionCounter = 0;
+
 function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
   return {
     instructions: {
@@ -74,70 +56,6 @@ function mockValue(type: string, currentValue: unknown, fieldId: string): unknow
   return `updated ${fieldId} at ${now}`;
 }
 
-function normalizeCommandOptions(optionsOrTimeout: number | CommandOptions): CommandOptions {
-  if (typeof optionsOrTimeout === 'number') {
-    return { timeoutMs: optionsOrTimeout };
-  }
-  return { timeoutMs: optionsOrTimeout.timeoutMs, env: optionsOrTimeout.env, input: optionsOrTimeout.input };
-}
-
-function defaultCommandRunner(argv: string[], optionsOrTimeout: number | CommandOptions): Promise<CommandRunResult> {
-  const options = normalizeCommandOptions(optionsOrTimeout);
-  return new Promise((resolve, reject) => {
-    if (!Array.isArray(argv) || argv.length === 0 || !argv[0]) {
-      reject(new Error('command argv must include a binary name'));
-      return;
-    }
-
-    const child = spawn(argv[0], argv.slice(1), {
-      env: {
-        ...process.env,
-        ...(options.env || {})
-      },
-      stdio: 'pipe'
-    });
-
-    const timeoutMs = Math.max(1000, Math.floor(options.timeoutMs));
-    let terminatedByTimeout = false;
-    const timer = setTimeout(() => {
-      terminatedByTimeout = true;
-      child.kill('SIGKILL');
-    }, timeoutMs);
-
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout.on('data', (chunk) => {
-      stdout += String(chunk);
-    });
-    child.stderr.on('data', (chunk) => {
-      stderr += String(chunk);
-    });
-
-    child.on('error', (error) => {
-      clearTimeout(timer);
-      reject(error);
-    });
-
-    child.on('close', (code, signal) => {
-      clearTimeout(timer);
-      resolve({
-        stdout: stdout.trim(),
-        stderr: stderr.trim(),
-        code,
-        signal,
-        killed: terminatedByTimeout || code === null,
-        termination: terminatedByTimeout ? 'timeout' : signal ? 'signal' : 'exit'
-      });
-    });
-
-    if (typeof options.input === 'string') {
-      child.stdin.write(options.input);
-    }
-    child.stdin.end();
-  });
-}
-
 function tryParseJson(input: string): unknown | undefined {
   try {
     return JSON.parse(input);
@@ -226,18 +144,23 @@ function parseFillResponse(output: string, source: string): FillResponse {
   return extracted;
 }
 
-async function runAndReadStdout(
-  commandRunner: CommandRunner,
-  argv: string[],
-  optionsOrTimeout: number | CommandOptions,
-  label: string
-): Promise<string> {
-  const result = await commandRunner(argv, optionsOrTimeout);
-  if (result.code !== 0) {
-    const reason = result.stderr || result.stdout || result.termination || `exit=${String(result.code)}`;
-    throw new Error(`${label} failed: ${reason}`);
-  }
-  return result.stdout.trim();
+function sanitizeSessionToken(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'x';
+}
+
+function nextEphemeralSessionCounter(): number {
+  ephemeralSessionCounter += 1;
+  return ephemeralSessionCounter;
+}
+
+function buildEphemeralSessionId(agentId: string, context: FillRunContext): string {
+  const templateId = sanitizeSessionToken(context.template.id || 'template');
+  const agent = sanitizeSessionToken(agentId || 'agent');
+  const attempt = Math.max(1, Math.floor(context.attempt || 1));
+  const now = Date.now().toString(36);
+  const pid = process.pid.toString(36);
+  const seq = nextEphemeralSessionCounter().toString(36);
+  return `plash-${agent}-${templateId}-a${attempt}-${pid}-${now}-${seq}`;
 }
 
 class MockFillRunner implements FillRunner {
@@ -253,10 +176,13 @@ class MockFillRunner implements FillRunner {
 class CommandFillRunner implements FillRunner {
   constructor(
     private readonly config: PlashboardConfig,
-    private readonly commandRunner: CommandRunner
+    private readonly commandRunner: CommandRunner | null
   ) {}
 
   async run(context: FillRunContext): Promise<FillResponse> {
+    if (!this.config.allow_command_fill) {
+      throw new Error('fill_provider=command is disabled; set allow_command_fill=true to enable it');
+    }
     if (!this.config.fill_command) {
       throw new Error('fill_provider=command but fill_command is not configured');
     }
@@ -280,29 +206,49 @@ class CommandFillRunner implements FillRunner {
 class OpenClawFillRunner implements FillRunner {
   constructor(
     private readonly config: PlashboardConfig,
-    private readonly commandRunner: CommandRunner
+    private readonly commandRunner: CommandRunner | null
   ) {}
 
   async run(context: FillRunContext): Promise<FillResponse> {
     const agentId = (this.config.openclaw_fill_agent_id || 'main').trim() || 'main';
     const timeoutSeconds = Math.max(10, Math.floor(this.config.session_timeout_seconds));
     const message = buildOpenClawMessage(context);
+    const ephemeral = this.config.session_strategy === 'ephemeral';
+    const sessionId = ephemeral ? buildEphemeralSessionId(agentId, context) : undefined;
+    const argv = ['openclaw', 'agent', '--agent', agentId, '--message', message, '--json', '--timeout', String(timeoutSeconds)];
+    if (sessionId) {
+      argv.push('--session-id', sessionId);
+    }
 
-    const output = await runAndReadStdout(
-      this.commandRunner,
-      ['openclaw', 'agent', '--agent', agentId, '--message', message, '--json', '--timeout', String(timeoutSeconds)],
-      {
-        timeoutMs: (timeoutSeconds + 30) * 1000
-      },
-      'openclaw fill'
-    );
-
-    return parseFillResponse(output, 'openclaw fill');
+    try {
+      const output = await runAndReadStdout(
+        this.commandRunner,
+        argv,
+        {
+          timeoutMs: (timeoutSeconds + 30) * 1000
+        },
+        'openclaw fill'
+      );
+
+      return parseFillResponse(output, 'openclaw fill');
+    } finally {
+      if (ephemeral && sessionId) {
+        // Best-effort cleanup through official CLI API; never mutate session files directly.
+        await runCommand(
+          this.commandRunner,
+          ['openclaw', 'sessions', 'delete', '--agent', agentId, '--session-id', sessionId, '--json'],
+          {
+            timeoutMs: Math.max(5, timeoutSeconds) * 1000
+          },
+          'openclaw ephemeral session cleanup'
+        );
+      }
+    }
   }
 }
 
 export function createFillRunner(config: PlashboardConfig, deps: FillRunnerDeps = {}): FillRunner {
-  const commandRunner = deps.commandRunner || defaultCommandRunner;
+  const commandRunner = deps.commandRunner ?? null;
   if (config.fill_provider === 'command') {
     return new CommandFillRunner(config, commandRunner);
   }