@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/schedule/__tests__/loop-command.test.ts

@@ -0,0 +1,360 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeLoopCommand } from '../loop-command.js';
+
+import { createTestAgentJobHost } from '@robota-sdk/agent-framework/testing';
+
+describe('fixed in-session loop', () => {
+  it('uses the host maintenance prompt for interval-only forms', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_default' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const options = { defaultPrompt: 'Tend only the current task and its PR.' };
+
+    expect((await executeLoopCommand(host, vi.fn(), '5m', options)).success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        cronExpression: expect.any(String),
+        agentInstruction: options.defaultPrompt,
+      }),
+    );
+  });
+
+  it('routes bare and prompt-only forms to the durable self-paced controller', async () => {
+    const createSelfPacedLoop = vi.fn().mockImplementation(async (instruction: string) => ({
+      loopId: 'loop_self', instruction, phase: 'pending', expiresAt: '2030-01-01T00:00:00.000Z',
+    }));
+    const spawnScheduledWake = vi.fn();
+    const host = createTestAgentJobHost({ spawnScheduledWake, createSelfPacedLoop });
+    const options = { defaultPrompt: 'Tend the current task.' };
+
+    expect((await executeLoopCommand(host, vi.fn(), '', options)).success).toBe(true);
+    expect((await executeLoopCommand(host, vi.fn(), 'check the build')).success).toBe(true);
+    expect(createSelfPacedLoop.mock.calls.map(([prompt]) => prompt)).toEqual([
+      options.defaultPrompt,
+      'check the build',
+    ]);
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+  });
+
+  it('marks omitted prompts for live override resolution without changing explicit prompts', async () => {
+    const createSelfPacedLoop = vi.fn().mockResolvedValue({
+      loopId: 'loop_default', expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'timer_default' });
+    const host = createTestAgentJobHost({ createSelfPacedLoop, spawnScheduledWake });
+    const resolveDefaultPrompt = vi.fn().mockReturnValue('current file prompt');
+    const options = { defaultPrompt: 'built-in prompt', resolveDefaultPrompt };
+
+    expect((await executeLoopCommand(host, vi.fn(), '', options)).success).toBe(true);
+    expect(createSelfPacedLoop).toHaveBeenCalledWith('current file prompt', { useDefaultPrompt: true });
+    expect((await executeLoopCommand(host, vi.fn(), '5m', options)).success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(expect.objectContaining({
+      agentInstruction: 'current file prompt', sessionLoopDefaultPrompt: true,
+    }));
+    expect((await executeLoopCommand(host, vi.fn(), 'explicit check', options)).success).toBe(true);
+    expect(createSelfPacedLoop).toHaveBeenLastCalledWith('explicit check');
+    expect(resolveDefaultPrompt).toHaveBeenCalledTimes(2);
+  });
+
+  it('lists and stops a self-paced loop by stable identity without touching schedules', async () => {
+    const stopSelfPacedLoop = vi.fn().mockResolvedValue(undefined);
+    const host = createTestAgentJobHost({
+      listSelfPacedLoops: () => [{
+        loopId: 'loop_self', instruction: 'check', phase: 'waiting',
+        createdAt: '2026-09-24T00:00:00.000Z', expiresAt: '2026-10-01T00:00:00.000Z',
+        revision: 1, generation: 1, fallbackUsed: false,
+        nextAllowedAt: '2026-09-24T00:20:00.000Z',
+      }],
+      stopSelfPacedLoop,
+    });
+    expect((await executeLoopCommand(host, vi.fn(), 'list')).message).toContain('loop_self');
+    expect((await executeLoopCommand(host, vi.fn(), 'stop loop_self')).success).toBe(true);
+    expect(stopSelfPacedLoop).toHaveBeenCalledExactlyOnceWith('loop_self', 'Loop stopped by user');
+  });
+
+  it('does not describe a previous delay as the next check while a loop is running', async () => {
+    const host = createTestAgentJobHost({
+      listSelfPacedLoops: () => [{
+        loopId: 'loop_running', instruction: 'check', phase: 'running',
+        createdAt: '2026-09-24T00:00:00.000Z', expiresAt: '2026-10-01T00:00:00.000Z',
+        revision: 2, generation: 1, fallbackUsed: false,
+        delaySeconds: 60, reason: 'previous check',
+      }],
+    });
+    const listed = await executeLoopCommand(host, vi.fn(), 'list');
+    expect(listed.message).toContain('loop_running [running]');
+    expect(listed.message).not.toContain('next 60s');
+  });
+
+  it('assigns every new loop a seven-day expiry', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_expiring' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const before = Date.now();
+    const result = await executeLoopCommand(host, vi.fn(), '5m check');
+    const after = Date.now();
+    const expiresAt = spawnScheduledWake.mock.calls[0]?.[0].sessionLoopExpiresAt as string;
+
+    expect(result.success).toBe(true);
+    expect(Date.parse(expiresAt)).toBeGreaterThanOrEqual(before + 7 * 24 * 60 * 60_000);
+    expect(Date.parse(expiresAt)).toBeLessThanOrEqual(after + 7 * 24 * 60 * 60_000);
+    expect(result.message).toContain(expiresAt);
+  });
+
+  it('does not promise a first fire before the requested interval elapses', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({
+      id: 'loop_first',
+      nextFireAt: '2026-09-24T00:10:00.000Z',
+    });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const clock = vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-09-24T00:09:00.000Z'));
+    try {
+      const result = await executeLoopCommand(host, vi.fn(), '7m check');
+      const input = spawnScheduledWake.mock.calls[0]?.[0] as {
+        sessionLoopFirstAllowedAt?: string;
+      };
+      expect(input.sessionLoopFirstAllowedAt).toBe('2026-09-24T00:16:00.000Z');
+      expect(result.message).toContain('First eligible at or after 2026-09-24T00:16:00.000Z');
+      expect(result.message).not.toContain('Next fire: 2026-09-24T00:10:00.000Z');
+    } finally {
+      clock.mockRestore();
+    }
+  });
+
+  it('refuses loop creation when the host kill switch is on, but still permits list', async () => {
+    const spawnScheduledWake = vi.fn();
+    const host = createTestAgentJobHost({
+      spawnScheduledWake,
+      listSchedules: vi.fn().mockReturnValue([
+        {
+          id: 'loop_existing',
+          kind: 'scheduled',
+          status: 'sleeping',
+          label: 'Loop: existing',
+          metadata: { sessionLoop: true },
+        },
+      ]),
+    });
+    const options = { disabled: true, defaultPrompt: 'Tend current task.' };
+
+    expect((await executeLoopCommand(host, vi.fn(), '5m check', options)).success).toBe(false);
+    const listed = await executeLoopCommand(host, vi.fn(), 'list', options);
+    expect(listed.success).toBe(true);
+    expect(listed.message).toContain('loop_existing');
+    expect(listed.message).toContain('disabled');
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+  });
+
+  it('uses a stable loop id to find a re-armed task after its runtime id changes', async () => {
+    const spawnScheduledWake = vi
+      .fn()
+      .mockImplementation(async (input: { sessionLoopId: string }) => ({
+        id: 'runtime_before_resume',
+        metadata: { sessionLoop: true, sessionLoopId: input.sessionLoopId },
+      }));
+    const listSchedules = vi.fn().mockImplementation(() => [
+      {
+        id: 'runtime_after_resume',
+        kind: 'scheduled',
+        status: 'sleeping',
+        label: 'Loop: check',
+        metadata: {
+          sessionLoop: true,
+          sessionLoopId: spawnScheduledWake.mock.calls[0]?.[0].sessionLoopId,
+        },
+      },
+    ]);
+    const host = createTestAgentJobHost({ spawnScheduledWake, listSchedules });
+    const cancel = vi.fn().mockResolvedValue(undefined);
+
+    const created = await executeLoopCommand(host, cancel, '5m check');
+    const loopId = (created.data as { loopId?: string }).loopId;
+    expect(loopId).toMatch(/^loop_[0-9a-f-]{36}$/);
+    expect(loopId).not.toBe('runtime_before_resume');
+    expect((await executeLoopCommand(host, cancel, 'list')).message).toContain(loopId);
+
+    const stopped = await executeLoopCommand(host, cancel, `stop ${loopId}`);
+    expect(stopped.success).toBe(true);
+    expect(cancel).toHaveBeenCalledWith('runtime_after_resume', 'Loop stopped by user');
+  });
+
+  it('refuses a fourth active loop without spawning a timer', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'unexpected' });
+    const listSchedules = vi.fn().mockReturnValue(
+      Array.from({ length: 3 }, (_, index) => ({
+        id: `runtime_${index}`,
+        kind: 'scheduled',
+        status: 'sleeping',
+        label: 'Loop: check',
+        metadata: { sessionLoop: true },
+      })),
+    );
+    const host = createTestAgentJobHost({ spawnScheduledWake, listSchedules });
+    const result = await executeLoopCommand(host, vi.fn(), '5m check');
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('3 active loops');
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+  });
+
+  it('reserves the final slot while a loop creation is still pending', async () => {
+    const finishSpawns: Array<(task: { id: string }) => void> = [];
+    const spawnScheduledWake = vi.fn().mockImplementation(
+      () =>
+        new Promise<{ id: string }>((resolve) => {
+          finishSpawns.push(resolve);
+        }),
+    );
+    const listSchedules = vi.fn().mockReturnValue(
+      Array.from({ length: 2 }, (_, index) => ({
+        id: `runtime_${index}`,
+        kind: 'scheduled',
+        status: 'sleeping',
+        metadata: { sessionLoop: true },
+      })),
+    );
+    const host = createTestAgentJobHost({ spawnScheduledWake, listSchedules });
+
+    const first = executeLoopCommand(host, vi.fn(), '5m first');
+    expect(spawnScheduledWake).toHaveBeenCalledTimes(1);
+    const secondPending = executeLoopCommand(host, vi.fn(), '5m second');
+    const spawnCount = spawnScheduledWake.mock.calls.length;
+    finishSpawns.forEach((resolve, index) => resolve({ id: `runtime_${index + 2}` }));
+    const second = await secondPending;
+    expect(second.success).toBe(false);
+    expect(second.message).toContain('3 active loops');
+    expect(spawnCount).toBe(1);
+
+    expect((await first).success).toBe(true);
+  });
+
+  it('creates a recurring scheduled wake with the requested prompt', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_task_1' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+
+    const result = await executeLoopCommand(host, vi.fn(), '5m check the build');
+
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({
+        label: 'Loop: check the build',
+        cronExpression: expect.any(String),
+        agentInstruction: 'check the build',
+        sessionLoop: true,
+        sessionLoopId: expect.stringMatching(/^loop_[0-9a-f-]{36}$/),
+      }),
+    );
+    const loopId = (result.data as { loopId: string }).loopId;
+    expect(result.message).toContain(`/loop stop ${loopId}`);
+    expect(result.data).toMatchObject({ taskId: 'loop_task_1', cadenceLabel: '5m' });
+    expect(result.data).toEqual(expect.objectContaining({ jitterSeconds: expect.any(Number) }));
+    expect(result.message).toMatch(/stable offset \+\d+s/);
+    expect((result.data as { jitterSeconds: number }).jitterSeconds).toBeLessThanOrEqual(150);
+    expect(spawnScheduledWake.mock.calls[0]![0].cronExpression)
+      .toBe((result.data as { cronExpression: string }).cronExpression);
+  });
+
+  it('accepts a trailing interval and reports the actual rounded cadence', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_task_2' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+
+    const result = await executeLoopCommand(host, vi.fn(), 'check the deploy every 7 minutes');
+
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cronExpression: expect.any(String),
+        agentInstruction: 'check the deploy',
+      }),
+    );
+    expect(result.message).toContain('10m (rounded up) local-clock step');
+    expect(result.message).toContain('daylight saving');
+    expect(result.data).toMatchObject({ requestedMs: 420_000, cadenceLabel: '10m' });
+  });
+
+  it('parses a malformed trailing interval in bounded time even after a long whitespace run', async () => {
+    const host = createTestAgentJobHost();
+    const started = performance.now();
+    const result = await executeLoopCommand(host, vi.fn(), `check${' '.repeat(50_000)}every nope`);
+
+    expect(result.success).toBe(false);
+    expect(performance.now() - started).toBeLessThan(250);
+  });
+
+  it('does not treat a prompt beginning with stop as a management command', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_task_3' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const result = await executeLoopCommand(host, vi.fn(), 'stopwatch the build every 2 minutes');
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({ agentInstruction: 'stopwatch the build' }),
+    );
+  });
+
+  it('accepts a leading interval when the prompt ends in non-time every-quantity text', async () => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_task_4' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const result = await executeLoopCommand(host, vi.fn(), '5m inspect every 2 files');
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({ agentInstruction: 'inspect every 2 files' }),
+    );
+  });
+
+  it('lists only active loops and stops only the selected loop', async () => {
+    const listSchedules = vi.fn().mockReturnValue([
+      {
+        id: 'loop_a',
+        kind: 'scheduled',
+        status: 'sleeping',
+        label: 'Loop: check A',
+        metadata: { sessionLoop: true },
+      },
+      {
+        id: 'loop_b',
+        kind: 'scheduled',
+        status: 'sleeping',
+        label: 'Scheduled: edited B',
+        metadata: { sessionLoop: true },
+      },
+      { id: 'schedule_c', kind: 'scheduled', status: 'sleeping', label: 'Scheduled: check C' },
+      {
+        id: 'loop_old',
+        kind: 'scheduled',
+        status: 'cancelled',
+        label: 'Loop: old',
+        metadata: { sessionLoop: true },
+      },
+    ]);
+    const createSelfPacedLoop = vi.fn();
+    const spawnScheduledWake = vi.fn();
+    const host = createTestAgentJobHost({ listSchedules, createSelfPacedLoop, spawnScheduledWake });
+    const cancel = vi.fn().mockResolvedValue(undefined);
+
+    const listed = await executeLoopCommand(host, cancel, 'list');
+    expect(listed.message).toContain('loop_a');
+    expect(listed.message).toContain('loop_b');
+    expect(listed.message).not.toContain('schedule_c');
+    expect(listed.message).not.toContain('loop_old');
+    expect(createSelfPacedLoop).not.toHaveBeenCalled();
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+
+    const stopped = await executeLoopCommand(host, cancel, 'stop loop_a');
+    expect(stopped.success).toBe(true);
+    expect(cancel).toHaveBeenCalledExactlyOnceWith('loop_a', 'Loop stopped by user');
+    expect(stopped.message).toContain('already-running turn may finish');
+
+    const unrelated = await executeLoopCommand(host, cancel, 'stop schedule_c');
+    expect(unrelated.success).toBe(false);
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['', '0m check', '2d check', '5x check', '5m check every 2m'])(
+    'rejects an unsupported or ambiguous loop form: %s',
+    async (args) => {
+      const spawnScheduledWake = vi.fn();
+      const host = createTestAgentJobHost({ spawnScheduledWake });
+      const result = await executeLoopCommand(host, vi.fn(), args);
+      expect(result.success).toBe(false);
+      expect(spawnScheduledWake).not.toHaveBeenCalled();
+    },
+  );
+});

package/src/schedule/__tests__/loop-jitter.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { jitterFixedLoop } from '../loop-jitter.js';
+
+describe('fixed-loop jitter', () => {
+  it('is stable for a loop identity and stays within half of a short interval', () => {
+    const cadence = { description: '5m', milliseconds: 300_000, cronExpression: '0 */5 * * * *' };
+    const first = jitterFixedLoop('loop_stable', cadence);
+    expect(jitterFixedLoop('loop_stable', cadence)).toEqual(first);
+    expect(first.jitterSeconds).toBeGreaterThanOrEqual(0);
+    expect(first.jitterSeconds).toBeLessThanOrEqual(150);
+    expect(first.cronExpression).toMatch(/^\d+ (?:\*\/5|\d+-59\/5) \* \* \* \*$/);
+  });
+
+  it('never adds more than 30 minutes to an hourly or daily slot', () => {
+    for (const cadence of [
+      { description: '2h', milliseconds: 7_200_000, cronExpression: '0 0 */2 * * *' },
+      { description: '24h', milliseconds: 86_400_000, cronExpression: '0 0 0 * * *' },
+    ]) {
+      const result = jitterFixedLoop('loop_stable', cadence);
+      expect(result.jitterSeconds).toBeLessThanOrEqual(1_800);
+      expect(result.cronExpression).toMatch(/^\d+ \d+ (?:\*\/2|0) \* \* \*$/);
+    }
+  });
+});

package/src/schedule/__tests__/monitor-model-permission-functional.test.ts

@@ -0,0 +1,126 @@
+/**
+ * A model-requested `/monitor` starts its command as a process, so the command is decided by the
+ * shell tool's own gate — the user's Bash/Shell rules — never by consent to `/monitor` itself.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createScheduleCommandModule } from '../schedule-command-module.js';
+
+import type { THooksConfig, TPermissionMode } from '@robota-sdk/agent-core';
+type ISandboxClient = NonNullable<Parameters<typeof scriptedSession>[0]['sandboxClient']>;
+
+/** A sandbox that would let every confined shell command run without a prompt. */
+const autoApprovingSandbox: ISandboxClient = {
+  filesystem: 'shared',
+  wrapCommand: (invocation) => invocation,
+  autoApproves: () => true,
+  run: () => Promise.reject(new Error('not used')),
+  readFile: () => Promise.reject(new Error('not used')),
+  writeFile: () => Promise.reject(new Error('not used')),
+};
+
+let harness: ScriptedSessionHarness | undefined;
+afterEach(async () => {
+  await harness?.dispose();
+  harness = undefined;
+});
+
+function session(options: {
+  permissionMode: TPermissionMode;
+  permissions?: { allow?: string[]; deny?: string[] };
+  hooks?: THooksConfig;
+  sandboxClient?: ISandboxClient;
+}): ScriptedSessionHarness {
+  harness = scriptedSession({
+    turns: [],
+    commandModules: [createScheduleCommandModule()],
+    backgroundTasks: true,
+    ...options,
+  });
+  return harness;
+}
+
+const MONITOR_ARGS = '"sleep 30" "ready" check the server';
+
+function monitorTasks(h: ScriptedSessionHarness) {
+  return h.session.listBackgroundTasks().filter((task) => task.kind === 'process');
+}
+
+describe('/monitor from the model is decided by the shell gate', () => {
+  it('a Bash deny rule refuses the monitored command, even under bypassPermissions', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      permissions: { deny: ['Bash(sleep *)'] },
+    });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('shell permission rules refused this command');
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('an allow rule for a different command does not approve it', async () => {
+    // Plan mode refuses an execute call no allow rule matches, so a prompt cannot stand in for it.
+    const h = session({ permissionMode: 'plan', permissions: { allow: ['Bash(echo *)'] } });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('starts the monitor when the shell rules allow that command', async () => {
+    const h = session({ permissionMode: 'plan', permissions: { allow: ['Bash(sleep *)'] } });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(true);
+    expect(monitorTasks(h)).toHaveLength(1);
+  });
+
+  it('leaves the user-typed command to the user', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      permissions: { deny: ['Bash(sleep *)'] },
+    });
+
+    const result = await h.command('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(true);
+  });
+
+  it('never takes the sandbox auto-approval: the monitor does not run inside the sandbox', async () => {
+    // Default mode would auto-run a sandboxed shell command. The monitor's process is started by the
+    // background-task manager, outside the sandbox, so it falls to the ask path — and with no one
+    // to ask here, it is refused rather than started unconfined.
+    const h = session({ permissionMode: 'default', sandboxClient: autoApprovingSandbox });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('runs the PreToolUse hooks, so a guardrail blocks the monitored command', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: 'Shell',
+            hooks: [{ type: 'command', command: 'echo "no sleeping" >&2; exit 2' }],
+          },
+        ],
+      },
+    });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+});

package/src/schedule/__tests__/schedule-command.test.ts

@@ -7,22 +7,62 @@
 import { describe, expect, it, vi } from 'vitest';
 
 import { executeMonitorCommand, executeScheduleCommand } from '../schedule-command.js';
+import { createScheduleCommandModule } from '../schedule-command-module.js';
 import { parseScheduleSpec } from '../schedule-spec-parser.js';
 
 import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import { createTestAgentJobHost } from '@robota-sdk/agent-framework/testing';
+
+describe('in-session repeat command', () => {
+  it('exposes a user-visible loop command through the default schedule module', () => {
+    const module = createScheduleCommandModule();
+    const executable = module.systemCommands?.find((command) => command.name === 'loop');
+    const palette = module.commandSources?.flatMap((source) => source.getCommands())
+      .find((command) => command.name === 'loop');
+
+    expect(executable).toBeDefined();
+    expect(palette).toBeDefined();
+    expect(executable?.requiresPermission).toBe(true);
+    expect(executable?.modelInvocable).toBe(true);
+    expect(executable?.userInvocable).toBe(true);
+    expect(palette?.subcommands?.map(({ name }) => name)).toEqual(['list', 'stop']);
+    expect(palette?.subcommands).toEqual(executable?.subcommands);
+  });
+});
 
 function mockHost(): {
   host: IAgentJobHostContext;
   scheduled: ReturnType<typeof vi.fn>;
   monitor: ReturnType<typeof vi.fn>;
+  listSchedules: ReturnType<typeof vi.fn>;
+  pauseSchedule: ReturnType<typeof vi.fn>;
+  resumeSchedule: ReturnType<typeof vi.fn>;
+  editSchedule: ReturnType<typeof vi.fn>;
 } {
   const scheduled = vi.fn().mockResolvedValue({ id: 'task_sched' });
   const monitor = vi.fn().mockResolvedValue({ id: 'task_mon' });
-  const host = {
+  const listSchedules = vi.fn().mockReturnValue([
+    {
+      id: 'sched_1',
+      status: 'sleeping',
+      label: 'daily',
+      kind: 'scheduled',
+      nextFireAt: '2030-01-01T00:00:00.000Z',
+      schedule: { cronExpression: '0 0 * * *' },
+    },
+  ]);
+  const pauseSchedule = vi.fn().mockResolvedValue(undefined);
+  const resumeSchedule = vi.fn().mockResolvedValue(undefined);
+  const editSchedule = vi.fn().mockResolvedValue(undefined);
+  const host = createTestAgentJobHost({
     spawnScheduledWake: scheduled,
     spawnMonitorWake: monitor,
-  } as unknown as IAgentJobHostContext;
-  return { host, scheduled, monitor };
+    listSchedules,
+    pauseSchedule,
+    resumeSchedule,
+    editSchedule,
+  });
+  return { host, scheduled, monitor, listSchedules, pauseSchedule, resumeSchedule, editSchedule };
 }
 
 describe('parseScheduleSpec (FLOW-005)', () => {
@@ -105,3 +145,103 @@ describe('executeScheduleCommand (FLOW-005)', () => {
     );
   });
 });
+
+// SELFHOST-012 TC-05: /schedule list|pause|resume|edit dispatch (mirror /background); create stays default.
+describe('executeScheduleCommand — management subcommands (SELFHOST-012)', () => {
+  it('list returns the caller schedules with cadence + status, no create', async () => {
+    const { host, listSchedules, scheduled } = mockHost();
+    const result = await executeScheduleCommand(host, 'list', Date.now());
+    expect(result.success).toBe(true);
+    expect(listSchedules).toHaveBeenCalledOnce();
+    expect(result.message).toContain('sched_1');
+    expect(result.message).toContain('[sleeping]');
+    expect(result.message).toContain('0 0 * * *');
+    expect(scheduled).not.toHaveBeenCalled(); // list is not a create
+  });
+
+  it('pause <id> / resume <id> dispatch to the host lifecycle calls', async () => {
+    const { host, pauseSchedule, resumeSchedule } = mockHost();
+    const paused = await executeScheduleCommand(host, 'pause sched_1', Date.now());
+    expect(paused.success).toBe(true);
+    expect(pauseSchedule).toHaveBeenCalledWith('sched_1');
+
+    const resumed = await executeScheduleCommand(host, 'resume sched_1', Date.now());
+    expect(resumed.success).toBe(true);
+    expect(resumeSchedule).toHaveBeenCalledWith('sched_1');
+  });
+
+  it('edit <id> <spec> parses the spec and patches the schedule', async () => {
+    const { host, editSchedule } = mockHost();
+    const result = await executeScheduleCommand(
+      host,
+      'edit sched_1 cron "*/5 * * * *" ping',
+      Date.now(),
+    );
+    expect(result.success).toBe(true);
+    expect(editSchedule).toHaveBeenCalledWith('sched_1', {
+      cronExpression: '*/5 * * * *',
+      agentInstruction: 'ping',
+      label: 'Scheduled: ping',
+    });
+  });
+
+  // CMD-009: create → edit → list must render the EDITED instruction. The host double applies the
+  // patch the way `BackgroundTaskManager.editScheduledTask` does (pinned in agent-executor), so a
+  // command that omits `label` from the patch leaves the list showing the creation-time text.
+  it('list renders the edited instruction, not the one captured at creation (CMD-009)', async () => {
+    const schedules: Array<Record<string, unknown>> = [];
+    const host = createTestAgentJobHost({
+      spawnScheduledWake: vi.fn().mockImplementation((input: Record<string, unknown>) => {
+        const task = {
+          id: 'sched_x',
+          status: 'sleeping',
+          kind: 'scheduled',
+          label: input['label'],
+          schedule: {
+            cronExpression: input['cronExpression'],
+            agentInstruction: input['agentInstruction'],
+          },
+        };
+        schedules.push(task);
+        return Promise.resolve(task);
+      }),
+      listSchedules: vi.fn().mockImplementation(() => schedules),
+      editSchedule: vi.fn().mockImplementation((id: string, patch: Record<string, unknown>) => {
+        const { label, ...schedulePatch } = patch;
+        const task = schedules.find((s) => s['id'] === id);
+        if (task === undefined) throw new Error(`no schedule ${id}`);
+        task['schedule'] = { ...(task['schedule'] as Record<string, unknown>), ...schedulePatch };
+        if (label !== undefined) task['label'] = label;
+        return Promise.resolve();
+      }),
+    });
+
+    await executeScheduleCommand(host, 'cron "0 9 * * *" write the standup', 0);
+    await executeScheduleCommand(host, 'edit sched_x cron "0 10 * * *" file the report', 0);
+    const listed = await executeScheduleCommand(host, 'list', 0);
+
+    expect(listed.message).toContain('file the report');
+    expect(listed.message).not.toContain('write the standup');
+    expect(listed.message).toContain('0 10 * * *');
+  });
+
+  it('pause/resume/edit without an id is a usage error (no host call)', async () => {
+    const { host, pauseSchedule, editSchedule } = mockHost();
+    const p = await executeScheduleCommand(host, 'pause', Date.now());
+    expect(p.success).toBe(false);
+    expect(p.message).toContain('Usage:');
+    expect(pauseSchedule).not.toHaveBeenCalled();
+
+    const e = await executeScheduleCommand(host, 'edit sched_1', Date.now());
+    expect(e.success).toBe(false);
+    expect(editSchedule).not.toHaveBeenCalled();
+  });
+
+  it('a create spec (in/cron) still creates — subcommand keywords do not collide', async () => {
+    const { host, scheduled, pauseSchedule } = mockHost();
+    const result = await executeScheduleCommand(host, 'in 5m summarize', 0);
+    expect(result.success).toBe(true);
+    expect(scheduled).toHaveBeenCalledOnce();
+    expect(pauseSchedule).not.toHaveBeenCalled();
+  });
+});