agentic-orchestrator 0.1.20 → 0.1.22

package/README.md

@@ -329,18 +329,15 @@ node apps/control-plane/scripts/validate-docker-mcp-contract.mjs --smoke
 
 ### `stop`
 
-Current behavior is a placeholder only:
-
-```json
-{ "ok": true, "data": { "status": "stop_not_implemented_yet" } }
-```
-
-It does not currently terminate active sessions or revoke leases.
+Stops the dashboard server by killing the process listening on a port.
 
 Example:
 
 ```bash
 aop stop
+
+# Stop a custom dashboard port
+aop stop --port 8080
 ```
 
 ### `delete`
@@ -511,7 +508,7 @@ Supported options:
 | `--all`                           | Aggregate across all projects (`status`); delete all features (`delete`)          |
 | `--auto`                          | Non-interactive init with all defaults (`init`)                                   |
 | `--force`                         | Overwrite existing config (`init`); force retry regardless of state (`retry`)     |
-| `--port <number>`                 | Dashboard listen port (default `3000`)                                            |
+| `--port <number>`                 | Dashboard listen port (`aop dashboard`) or stop target port (`aop stop`)          |
 | `--dev`                           | Start dashboard in Next.js dev mode                                               |
 | `--foreground`                    | Keep dashboard server in the foreground                                           |
 | `--message <text>`                | Message to deliver to agent session (`send`)                                      |

package/agentic/orchestrator/prompts/planner.system.md

@@ -21,7 +21,13 @@ Every `PLAN_SUBMISSION` must include ALL of the following fields in `plan_json`:
 | `acceptance_criteria` | string[] (min 1) | Conditions that must all be met before merge                                                      |
 | `gate_profile`        | string           | Gate profile name (e.g. `"fast"` or `"full"`)                                                     |
 
-Optional fields: `gate_targets`, `risk`, `revision_of`, `revision_reason`, `verification_overrides`.
+Optional fields (with types):
+
+- `gate_targets`: `string[]` — explicit gate mode names to run
+- `risk`: **`string[]`** — list of risk statements (e.g. `["Schema migration may require downtime"]`). **Must be an array, never a plain string.**
+- `revision_of`: `integer` — plan_version this revises
+- `revision_reason`: `string` — why the plan was revised
+- `verification_overrides`: `object`
 
 ### Minimal example
 

package/apps/control-plane/src/cli/help-command-handler.ts

@@ -59,8 +59,12 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     ],
   },
   [CliCommand.Stop]: {
-    usage: 'aop stop',
-    description: 'Signal the running supervisor to stop gracefully.',
+    usage: 'aop stop [flags]',
+    description: 'Stop the dashboard server by terminating listeners on a target port.',
+    flags: [
+      { flag: '--port <number>', description: 'Port to stop (default: 3000)' },
+      { flag: '--project <name>', description: 'Use the project default dashboard port' },
+    ],
   },
   [CliCommand.Delete]: {
     usage: 'aop delete [flags]',

package/apps/control-plane/src/cli/init-command-handler.ts

@@ -424,7 +424,7 @@ runtime:
   default_provider: ${wizard.defaultProvider}
   default_model: ${wizard.defaultModel}
   worker_provider_mode: live
-  worker_response_timeout_ms: 120000
+  worker_response_timeout_ms: 600000
   max_consecutive_no_progress_iterations: 2
 ${providerConfigEnvLine}  role_provider_overrides: {}
 `;

package/apps/control-plane/src/cli/stop-command-handler.ts

@@ -1,5 +1,169 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_DASHBOARD_PORT = 3000;
+
+interface StopCommandOptions {
+  port?: number;
+}
+
+function normalizePort(port: number | undefined): number {
+  if (typeof port === 'number' && Number.isInteger(port) && port >= 1 && port <= 65535) {
+    return port;
+  }
+  return DEFAULT_DASHBOARD_PORT;
+}
+
+function parsePids(raw: string): number[] {
+  const values = raw
+    .split(/\r?\n/)
+    .map((line) => Number.parseInt(line.trim(), 10))
+    .filter((value) => Number.isInteger(value) && value > 0);
+  return [...new Set(values)];
+}
+
+function extractStdout(result: unknown): string {
+  if (typeof result === 'string') {
+    return result;
+  }
+  if (!result || typeof result !== 'object') {
+    return '';
+  }
+  const record = result as Record<string, unknown>;
+  const stdout = record.stdout;
+  if (typeof stdout === 'string') {
+    return stdout;
+  }
+  if (stdout instanceof Uint8Array) {
+    return Buffer.from(stdout).toString('utf8');
+  }
+  return '';
+}
+
+function readErrorCode(error: unknown): string | number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const record = error as Record<string, unknown>;
+  const { code } = record;
+  return typeof code === 'string' || typeof code === 'number' ? code : undefined;
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return readErrorCode(error) === 'ENOENT';
+}
+
+function isNoMatchesError(error: unknown): boolean {
+  return readErrorCode(error) === 1;
+}
+
+async function findPidsOnWindows(port: number): Promise<number[]> {
+  const stdout = extractStdout(await execFileAsync('netstat', ['-ano', '-p', 'tcp']));
+  const pids: number[] = [];
+  const lines = stdout.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line.includes('LISTENING')) {
+      continue;
+    }
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 5) {
+      continue;
+    }
+    const localAddress = parts[1];
+    const pid = Number.parseInt(parts[4], 10);
+    const localPortRaw = localAddress.includes(':') ? localAddress.split(':').pop() : null;
+    const localPort = localPortRaw ? Number.parseInt(localPortRaw, 10) : Number.NaN;
+    if (localPort === port && Number.isInteger(pid) && pid > 0) {
+      pids.push(pid);
+    }
+  }
+  return [...new Set(pids)];
+}
+
+async function findPidsOnUnix(port: number): Promise<number[]> {
+  try {
+    const stdout = extractStdout(
+      await execFileAsync('lsof', ['-nP', '-iTCP:' + String(port), '-sTCP:LISTEN', '-t']),
+    );
+    return parsePids(stdout);
+  } catch (error) {
+    if (isNoMatchesError(error)) {
+      return [];
+    }
+    if (isNotFoundError(error)) {
+      // Minimal fallback when lsof is unavailable.
+      const stdout = extractStdout(
+        await execFileAsync('ss', ['-ltnp', 'sport = :' + String(port)]),
+      );
+      const pidMatches = [...stdout.matchAll(/pid=(\d+)/g)];
+      const pids = pidMatches
+        .map((match) => Number.parseInt(match[1], 10))
+        .filter((value) => Number.isInteger(value) && value > 0);
+      return [...new Set(pids)];
+    }
+    throw error;
+  }
+}
+
+async function findListeningPids(port: number): Promise<number[]> {
+  if (process.platform === 'win32') {
+    return await findPidsOnWindows(port);
+  }
+  return await findPidsOnUnix(port);
+}
+
+async function killPid(pid: number): Promise<void> {
+  if (process.platform === 'win32') {
+    await execFileAsync('taskkill', ['/PID', String(pid), '/F']);
+    return;
+  }
+  await execFileAsync('kill', ['-TERM', String(pid)]);
+}
+
+function isAlreadyExitedError(error: unknown): boolean {
+  const code = readErrorCode(error);
+  return code === 'ESRCH' || code === 1;
+}
+
 export class StopCommandHandler {
-  execute(): Promise<unknown> {
-    return Promise.resolve({ ok: true, data: { status: 'stop_not_implemented_yet' } });
+  async execute(options: StopCommandOptions = {}): Promise<unknown> {
+    const port = normalizePort(options.port);
+    const pids = await findListeningPids(port);
+    if (pids.length === 0) {
+      return {
+        ok: true,
+        data: {
+          command: 'stop',
+          target: 'dashboard',
+          port,
+          stopped: false,
+          message: `No process is listening on port ${port}`,
+        },
+      };
+    }
+
+    for (const pid of pids) {
+      try {
+        await killPid(pid);
+      } catch (error) {
+        if (isAlreadyExitedError(error)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    return {
+      ok: true,
+      data: {
+        command: 'stop',
+        target: 'dashboard',
+        port,
+        stopped: true,
+        pids,
+        message: `Stopped listener(s) on port ${port}`,
+      },
+    };
   }
 }

package/apps/control-plane/src/interfaces/cli/bootstrap.ts

@@ -253,6 +253,17 @@ export async function runCli(
       return 0;
     }
 
+    if (options.command === CliCommand.Stop) {
+      const handler = new StopCommandHandler();
+      const defaultDashboardPort =
+        selectedProject?.dashboard_port ?? multiConfig?.defaults?.dashboard_port;
+      const payload = await handler.execute({
+        port: options.port ?? defaultDashboardPort,
+      });
+      printPayload(payload);
+      return 0;
+    }
+
     const transport = parser.resolveTransport(options.transport);
     const runId = `run:${crypto.randomUUID()}`;
 
@@ -380,13 +391,6 @@ export async function runCli(
       return 0;
     }
 
-    if (options.command === CliCommand.Stop) {
-      const handler = new StopCommandHandler();
-      const payload = await handler.execute();
-      printPayload(payload);
-      return 0;
-    }
-
     if (options.command === CliCommand.Delete) {
       const handler = new DeleteCommandHandler(toolClient, runId);
       const payload = await handler.execute(options);

package/apps/control-plane/test/bootstrap-edge-cases.spec.ts

@@ -13,6 +13,17 @@ const ensureLoadedMock = vi.hoisted(() => vi.fn(async () => undefined));
 const createToolingRuntimeMock = vi.hoisted(() => vi.fn(async () => ({ runtime: 'ok' })));
 const resolveToolClientMock = vi.hoisted(() => vi.fn());
 const toolCallMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, data: {} })));
+const stopExecuteMock = vi.hoisted(() =>
+  vi.fn(async (options?: { port?: number }) => ({
+    ok: true,
+    data: {
+      command: 'stop',
+      target: 'dashboard',
+      port: options?.port ?? 3000,
+      stopped: false,
+    },
+  })),
+);
 
 /** Allows per-test control of getPolicySnapshot return value */
 const policySnapshotOverride = vi.hoisted(() => ({
@@ -98,6 +109,14 @@ vi.mock('../src/cli/dashboard-command-handler.js', () => ({
   },
 }));
 
+vi.mock('../src/cli/stop-command-handler.js', () => ({
+  StopCommandHandler: class StopCommandHandler {
+    async execute(options?: { port?: number }) {
+      return await stopExecuteMock(options);
+    }
+  },
+}));
+
 vi.mock('../src/cli/run-command-handler.js', () => ({
   RunCommandHandler: class RunCommandHandler {
     async execute() {
@@ -156,6 +175,7 @@ describe('bootstrap edge-case branch coverage', () => {
     toolCallMock.mockResolvedValue({ ok: true, data: { features: [] } });
     ensureLoadedMock.mockClear();
     createToolingRuntimeMock.mockClear();
+    stopExecuteMock.mockClear();
     stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
     policySnapshotOverride.value = {};
     kernelThrowOverride.value = null;
@@ -288,6 +308,21 @@ describe('bootstrap edge-case branch coverage', () => {
     expect(code).toBe(0);
   });
 
+  it('GIVEN_stop_command_without_port_option_WHEN_executed_THEN_uses_project_default_port', async () => {
+    const proj1 = path.join(tmpDir, 'proj1');
+    await fs.mkdir(proj1, { recursive: true });
+    await writeMultiProjectYaml(
+      tmpDir,
+      `version: "1.0"\nprojects:\n  - name: proj1\n    path: ${proj1}\n    dashboard_port: 4111\n`,
+    );
+
+    const { runCli } = await import('../src/interfaces/cli/bootstrap.js');
+    const code = await runCli(['stop', '--project', 'proj1'], { cwd: tmpDir, env: process.env });
+
+    expect(code).toBe(0);
+    expect(stopExecuteMock).toHaveBeenCalledWith({ port: 4111 });
+  });
+
   it('GIVEN_status_all_with_one_project_throwing_error_without_code_WHEN_executed_THEN_uses_fallback_code', async () => {
     // Covers line 205: typed.code ?? ERROR_CODES.INTERNAL_ERROR when typed.code is undefined
     const proj1 = path.join(tmpDir, 'proj1');

package/apps/control-plane/test/bootstrap.spec.ts

@@ -11,6 +11,17 @@ const resolveToolClientMock = vi.hoisted(() => vi.fn());
 const toolCallMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, data: {} })));
 const readlineQuestionMock = vi.hoisted(() => vi.fn(async () => ''));
 const readlineCloseMock = vi.hoisted(() => vi.fn());
+const stopExecuteMock = vi.hoisted(() =>
+  vi.fn(async (options?: { port?: number }) => ({
+    ok: true,
+    data: {
+      command: 'stop',
+      target: 'dashboard',
+      port: options?.port ?? 3000,
+      stopped: false,
+    },
+  })),
+);
 
 vi.mock('node:readline/promises', () => ({
   default: {
@@ -88,6 +99,14 @@ vi.mock('../src/cli/dashboard-command-handler.js', () => ({
   },
 }));
 
+vi.mock('../src/cli/stop-command-handler.js', () => ({
+  StopCommandHandler: class StopCommandHandler {
+    async execute(options?: { port?: number }) {
+      return await stopExecuteMock(options);
+    }
+  },
+}));
+
 vi.mock('../src/cli/run-command-handler.js', () => ({
   RunCommandHandler: class RunCommandHandler {
     async execute() {
@@ -151,6 +170,7 @@ describe('bootstrap runCli', () => {
     toolCallMock.mockClear();
     ensureLoadedMock.mockClear();
     createToolingRuntimeMock.mockClear();
+    stopExecuteMock.mockClear();
     stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
   });
 
@@ -159,13 +179,25 @@ describe('bootstrap runCli', () => {
     vi.clearAllMocks();
   });
 
-  it('GIVEN_stop_command_WHEN_executed_THEN_returns_stop_not_implemented_yet', async () => {
+  it('GIVEN_stop_command_WHEN_executed_THEN_returns_stop_dashboard_payload', async () => {
     const { runCli } = await import('../src/interfaces/cli/bootstrap.js');
     const code = await runCli(['stop'], { cwd: '/tmp', env: process.env });
 
     const writes = asJsonWrites(stdoutSpy);
     expect(code).toBe(0);
-    expect(writes[0]).toMatchObject({ ok: true, data: { status: 'stop_not_implemented_yet' } });
+    expect(stopExecuteMock).toHaveBeenCalledWith({ port: undefined });
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: { command: 'stop', target: 'dashboard', port: 3000, stopped: false },
+    });
+  });
+
+  it('GIVEN_stop_command_with_port_WHEN_executed_THEN_passes_port_to_handler', async () => {
+    const { runCli } = await import('../src/interfaces/cli/bootstrap.js');
+    const code = await runCli(['stop', '--port', '8080'], { cwd: '/tmp', env: process.env });
+
+    expect(code).toBe(0);
+    expect(stopExecuteMock).toHaveBeenCalledWith({ port: 8080 });
   });
 
   it('GIVEN_delete_command_with_feature_id_and_yes_WHEN_executed_THEN_calls_toolClient', async () => {

package/apps/control-plane/test/cli-helpers.spec.ts

@@ -486,14 +486,15 @@ describe('HelpCommandHandler', () => {
     expect(result.data.help).toContain('Commands:');
   });
 
-  it('GIVEN_command_without_flags_WHEN_execute_called_THEN_renders_without_flags_section', async () => {
+  it('GIVEN_stop_help_WHEN_execute_called_THEN_renders_stop_flags_section', async () => {
     const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
     const handler = new HelpCommandHandler();
     const result = handler.execute('stop');
     expect(result.ok).toBe(true);
-    expect(result.data.help).toContain('Usage: aop stop');
-    // stop has no flags
-    expect(result.data.help).not.toContain('Flags:');
+    expect(result.data.help).toContain('Usage: aop stop [flags]');
+    expect(result.data.help).toContain('Flags:');
+    expect(result.data.help).toContain('--port <number>');
+    expect(result.data.help).toContain('--project <name>');
   });
 
   it('GIVEN_delete_help_WHEN_execute_called_THEN_documents_yes_for_destructive_delete', async () => {

package/apps/control-plane/test/cli.unit.spec.ts

@@ -348,14 +348,19 @@ describe('aop CLI unit', () => {
     });
   });
 
-  it('GIVEN_stop_command_WHEN_main_runs_THEN_returns_not_implemented_status', async () => {
+  it('GIVEN_stop_command_WHEN_main_runs_THEN_returns_stop_dashboard_payload', async () => {
     const code = await main(['stop'], { cwd, env: {} as NodeJS.ProcessEnv });
     const writes = asJsonWrites(stdoutSpy);
 
     expect(code).toBe(0);
     expect(writes[0]).toMatchObject({
       ok: true,
-      data: { status: 'stop_not_implemented_yet' },
+      data: expect.objectContaining({
+        command: 'stop',
+        target: 'dashboard',
+        port: 3000,
+        stopped: expect.any(Boolean),
+      }),
     });
   });
 

package/apps/control-plane/test/dashboard-client.spec.ts

@@ -118,6 +118,57 @@ describe('dashboard aop client mapping', () => {
     expect(payload.features[0].gates).toEqual({ fast: 'pass', full: 'fail', merge: 'na' });
   });
 
+  it('GIVEN_building_feature_without_activity_state_but_running_role_WHEN_readDashboardStatus_THEN_infers_active_activity', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({ active: ['feature_build'], blocked: [], merged: [], blocked_queue: [] }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_build',
+      [
+        'feature_id: feature_build',
+        'version: 1',
+        'status: building',
+        'role_status:',
+        '  planner: done',
+        '  builder: running',
+        '  qa: ready',
+      ].join('\n'),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.features[0].activity_state).toBe('active');
+  });
+
+  it('GIVEN_building_feature_without_activity_state_and_stale_timestamp_WHEN_readDashboardStatus_THEN_infers_idle_activity', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({ active: ['feature_idle'], blocked: [], merged: [], blocked_queue: [] }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_idle',
+      [
+        'feature_id: feature_idle',
+        'version: 1',
+        'status: building',
+        'last_updated: 2026-01-01T00:00:00Z',
+      ].join('\n'),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.features[0].activity_state).toBe('idle');
+  });
+
   it('GIVEN_blocked_queue_feature_without_state_WHEN_readDashboardStatus_THEN_phase_is_blocked', async () => {
     const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
     tempRoots.push(repoRoot);