fix: improve PostgreSQL startup reliability and agent documentation

Dockerfile

@@ -31,9 +31,23 @@ RUN apt-get update && apt-get install -y \
     && ln -s $(which fdfind) /usr/local/bin/fd
 
 # Configure PostgreSQL for local development use by agents
+# - User: postgres, Password: postgres
+# - Connection: postgresql://postgres:postgres@localhost:5432/postgres
 RUN mkdir -p /run/postgresql && chown -R postgres:postgres /run/postgresql \
     && mkdir -p /var/lib/postgresql/data && chown -R postgres:postgres /var/lib/postgresql \
-    && su postgres -c "/usr/lib/postgresql/*/bin/initdb -D /var/lib/postgresql/data"
+    && su postgres -c "/usr/lib/postgresql/*/bin/initdb -D /var/lib/postgresql/data" \
+    && { \
+        echo "# PostgreSQL Client Authentication Configuration"; \
+        echo "# TYPE  DATABASE  USER  ADDRESS  METHOD"; \
+        echo "local   all       all            trust"; \
+        echo "host    all       all   127.0.0.1/32  md5"; \
+        echo "host    all       all   ::1/128       md5"; \
+        echo "host    all       all   0.0.0.0/0     md5"; \
+    } > /var/lib/postgresql/data/pg_hba.conf \
+    && chown postgres:postgres /var/lib/postgresql/data/pg_hba.conf \
+    && su postgres -c "/usr/lib/postgresql/*/bin/pg_ctl start -D /var/lib/postgresql/data -l /tmp/postgres.log -w" \
+    && su postgres -c "psql -c \"ALTER USER postgres WITH PASSWORD 'postgres';\"" \
+    && su postgres -c "/usr/lib/postgresql/*/bin/pg_ctl stop -D /var/lib/postgresql/data"
 
 # Install ast-grep
 RUN ARCH=$(dpkg --print-architecture) && \

src/agents/prompts/templates/partials/environment.eta

@@ -1,6 +1,12 @@
 ## Available Environment
 
-- **PostgreSQL**: Local server running. Connect via `psql -U postgres`.
+- **PostgreSQL**: Local server running on port 5432
+  - **Connection string**: `postgresql://postgres:postgres@localhost:5432/postgres`
+  - **Connect via CLI**: `psql -U postgres -h localhost`
+  - **Start**: `su postgres -c 'pg_ctl start -D /var/lib/postgresql/data -l /tmp/postgres.log'`
+  - **Stop**: `su postgres -c 'pg_ctl stop -D /var/lib/postgresql/data'`
+  - **Status**: `su postgres -c 'pg_ctl status -D /var/lib/postgresql/data'`
+  - **Create database**: `psql -U postgres -h localhost -c 'CREATE DATABASE mydb;'`
 - **Node.js 22**: With npm, pnpm, yarn, bun
 - **Git & GitHub CLI**: `git` and `gh` commands available
 - **Search tools** (use via Tmux for fast codebase exploration):

src/agents/utils/setup.ts

@@ -13,14 +13,53 @@ let postgresStarted = false;
 export async function startPostgres(): Promise<void> {
 	if (postgresStarted) return;
 
+	const PG_DATA = '/var/lib/postgresql/data';
+	const PG_LOG = '/tmp/postgres.log';
+
+	try {
+		// Check if PostgreSQL is already running
+		const statusResult = await execCommand(
+			'su',
+			['postgres', '-c', `pg_ctl status -D ${PG_DATA}`],
+			'/',
+		);
+
+		if (statusResult.stdout.includes('server is running')) {
+			logger.info('PostgreSQL already running');
+			postgresStarted = true;
+			return;
+		}
+	} catch {
+		// Not running, continue to start it
+	}
+
 	// Start PostgreSQL as postgres user
-	await execCommand(
-		'su',
-		['postgres', '-c', 'pg_ctl start -D /var/lib/postgresql/data -l /tmp/postgres.log'],
-		'/',
-	);
+	logger.info('Starting PostgreSQL...');
+	try {
+		await execCommand('su', ['postgres', '-c', `pg_ctl start -D ${PG_DATA} -l ${PG_LOG} -w`], '/');
+	} catch (err) {
+		logger.error('Failed to start PostgreSQL', { error: String(err) });
+		throw new Error(`PostgreSQL failed to start. Check ${PG_LOG} for details. Error: ${err}`);
+	}
+
+	// Verify it's actually running
+	try {
+		const verifyResult = await execCommand(
+			'su',
+			['postgres', '-c', `pg_ctl status -D ${PG_DATA}`],
+			'/',
+		);
+
+		if (!verifyResult.stdout.includes('server is running')) {
+			throw new Error('PostgreSQL started but status check failed');
+		}
+	} catch (err) {
+		logger.error('PostgreSQL status check failed after start', { error: String(err) });
+		throw new Error(`PostgreSQL failed to start properly: ${err}`);
+	}
+
 	postgresStarted = true;
-	logger.info('PostgreSQL started');
+	logger.info('PostgreSQL started successfully');
 }
 
 // ============================================================================