Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: return JSON errors from CoS Runner routes and stop spawn rejections failing shutdown (#11765)

[._.]/ Adam Eivy2181b68737c2
diff --git a/server/cos-runner/index.js b/server/cos-runner/index.js
index d941eed1c8..8bd53aec9a 100644
--- a/server/cos-runner/index.js
+++ b/server/cos-runner/index.js
@@ -1025,6 +1025,19 @@ async function cleanupOrphanedAgents() {
return orphaned;
}
+// Terminal JSON error handler: without it Express answers a thrown route error
+// with an HTML page and drops err.code, which cosRunnerClient cannot classify.
+app.use((err, _req, res, next) => {
+ if (res.headersSent) return next(err);
+ const isValidation = err?.name === 'ZodError' || Array.isArray(err?.issues);
+ const status = isValidation ? 400 : Number.isInteger(err?.status) ? err.status : 500;
+ const message = Array.isArray(err?.issues) ? bodyErrorMessage(err) : err?.message || 'Internal runner error';
+ res.status(status).json({
+ error: message,
+ code: isValidation ? 'VALIDATION_ERROR' : err?.code || 'RUNNER_ERROR',
+ });
+});
+
/**
* Start the server
*/
diff --git a/server/cos-runner/shutdown.js b/server/cos-runner/shutdown.js
index 56cc7117d9..c29bf9446a 100644
--- a/server/cos-runner/shutdown.js
+++ b/server/cos-runner/shutdown.js
@@ -28,6 +28,15 @@ export function createRunnerShutdown({
return promise;
};
+ // HTTP route rejections (503 maintenance hold, 409 duplicate grant, validation)
+ // are answered by the Express error middleware; only drain work may flip `failed`.
+ const trackRequest = (work) => {
+ const promise = (async () => work())();
+ const settled = promise.then(() => {}, () => {}).finally(() => pending.delete(settled));
+ pending.add(settled);
+ return promise;
+ };
+
const rejectSpawn = (res) => {
if (!stopping) return false;
res.status(503).json({ error: 'Runner is shutting down', code: 'SHUTTING_DOWN' });
@@ -36,7 +45,7 @@ export function createRunnerShutdown({
const spawnRoute = (handler) => (req, res) => {
if (rejectSpawn(res)) return;
- if (!admission) return trackWork(() => handler(req, res));
+ if (!admission) return trackRequest(() => handler(req, res));
let permit;
try {
permit = admission.admit('runner', String(req.body?.agentId ?? '').slice(0, 256), {
@@ -45,7 +54,7 @@ export function createRunnerShutdown({
} catch (err) { return res.status(err.status || 503).json({ error: err.message, code: err.code }); }
const entry = { permit, handedOff: false };
spawnPermits.set(permit.id, entry);
- return trackWork(() => permit.run(async () => {
+ return trackRequest(() => permit.run(async () => {
try {
const result = await handler(req, res);
if (!entry.handedOff) permit.finish();
diff --git a/server/cos-runner/shutdown.test.js b/server/cos-runner/shutdown.test.js
index 2109574d4d..c6fe12080c 100644
--- a/server/cos-runner/shutdown.test.js
+++ b/server/cos-runner/shutdown.test.js
@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
import { createDatabaseMaintenanceJournal } from '../lib/databaseMaintenanceJournal.js';
import { join, basename } from 'node:path';
import { runInNewContext } from 'node:vm';
+import { z } from 'zod';
// The runner body runs in a VM, but its extracted completion helper and
// publication/rollback boundary must stay real. Share the VM's virtual files
@@ -131,7 +132,8 @@ function runner(assertDatabaseAdmission = vi.fn()) {
} }, res);
return { res, done };
};
- return { request, process, server, io, state, files, children, spawn, pty, commandExists, writeFile, withState, drainState };
+ const errorHandler = () => app.use.mock.calls.map(c => c[0]).findLast(fn => fn.length === 4);
+ return { errorHandler, request, process, server, io, state, files, children, spawn, pty, commandExists, writeFile, withState, drainState };
}
beforeEach(() => {
@@ -289,4 +291,34 @@ describe('runner shutdown through its real spawn and signal handlers', () => {
expect(run.process.exit).not.toHaveBeenCalled();
expect(run.state.agents['agent-1']).toBeDefined();
});
+
+ it('answers rejected spawns with JSON error bodies and keeps a clean shutdown exit', async () => {
+ const maintenance = Object.assign(new Error('Database maintenance in progress'), { status: 503, code: 'DATABASE_MAINTENANCE' });
+ const run = runner(vi.fn(() => { throw maintenance; }));
+ const handler = run.errorHandler();
+ const reply = () => ({ headersSent: false, status(code) { this.statusCode = code; return this; }, json(body) { this.body = body; } });
+ for (const path of ['/spawn', '/spawn-tui']) {
+ const err = await run.request(path).done.catch(e => e);
+ const res = reply();
+ handler(err, {}, res, vi.fn());
+ expect(res.statusCode).toBe(503);
+ expect(res.body).toEqual({ error: 'Database maintenance in progress', code: 'DATABASE_MAINTENANCE' });
+ }
+ const zodErr = z.object({ agentId: z.string() }).safeParse({}).error;
+ const res = reply();
+ handler(zodErr, {}, res, vi.fn());
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'VALIDATION_ERROR', error: expect.stringContaining('agentId') });
+ const generic = reply();
+ handler(new Error('boom'), {}, generic, vi.fn());
+ expect(generic.statusCode).toBe(500);
+ expect(generic.body).toEqual({ error: 'boom', code: 'RUNNER_ERROR' });
+ const sent = { ...reply(), headersSent: true };
+ const next = vi.fn();
+ handler(maintenance, {}, sent, next);
+ expect(next).toHaveBeenCalledWith(maintenance);
+ run.process.emit('SIGTERM');
+ await vi.advanceTimersByTimeAsync(0);
+ expect(run.process.exit).toHaveBeenCalledExactlyOnceWith(0);
+ });
});