refactor: migrate maintained runtime leaves to TypeScript (#989)

## Summary
- migrate nine maintained CommonJS runtime modules to strict TypeScript
across runtime boundaries, task input handling, CLI formatting,
buffering/report formatting, and attach socket paths
- preserve emitted CommonJS module keys, function arities, runtime
paths, socket permissions, and package contents
- keep each concern in its own reviewable commit while shipping the
stack as one PR

## Migrated modules
- `src/ledger-sequence.ts`
- `src/task-startup-error.ts`
- `src/input-helpers.ts`
- `src/task-runner.ts`
- `cli/event-copy.ts`
- `cli/message-formatter-utils.ts`
- `src/message-buffer.ts`
- `src/template-validation/report-formatter.ts`
- `src/attach/socket-paths.ts`

## Validation
- `npm run typecheck`
- `npm run lint -- --quiet`
- focused unit/integration suites for every migrated surface
- built-package runtime smoke test
- public export key and function-arity parity checks where applicable
- Opcore graph update, repository check, changed/staged checks, Sense,
and introduced-change validation

## Scope
These are maintained Node runtime surfaces. Current native-v2 roadmap
issue #986 explicitly defers attach/reconnect and does not replace these
modules in its near-term foreground-only scope. No behavior or feature
changes are intended.

Author: tomdps

.gitignore

@@ -58,6 +58,8 @@ report/
 .turbo/
 *.cast
 # Generated/temp files
+cli/event-copy.js
+cli/message-formatter-utils.js
 test-metadata-manual.sh
 test-isolated-fix.js
 lib/agent-cli-provider/
@@ -138,6 +140,11 @@ lib/settings-validation.d.ts
 lib/settings-issue-providers.js
 lib/settings-issue-providers.d.ts
 src/guidance-topics.js
+src/input-helpers.js
+src/ledger-sequence.js
+src/message-buffer.js
+src/task-startup-error.js
+src/task-runner.js
 src/omp-blob-root.js
 src/omp-config-overlay.js
 task-lib/completion.js
@@ -152,8 +159,10 @@ src/agent/critical-agent-policy.js
 src/agent/provider-control-plane.js
 src/agent/structured-output-error.js
 src/agent/validation-platform.js
+src/attach/socket-paths.js
 src/providers/anthropic/index.js
 src/providers/capabilities.js
 src/providers/google/index.js
 src/providers/openai/index.js
 src/providers/opencode/index.js
+src/template-validation/report-formatter.js

cli/event-copy.js cli/event-copy.tscli/event-copy.js renamed to cli/event-copy.ts

@@ -1,12 +1,12 @@
 const EVENT_COPY = {
   IMPLEMENTATION_READY: 'Implementation ready',
   PR_CREATED: 'Pull request created',
-};
+} as const;
 
-function formatMergeStatus(merged) {
+function formatMergeStatus(merged: unknown): string | null {
   if (merged === true || merged === 'true') return 'merged';
   if (merged === false || merged === 'false') return 'auto-merge pending approval';
   return null;
 }
 
-module.exports = { EVENT_COPY, formatMergeStatus };
+export = { EVENT_COPY, formatMergeStatus };

cli/message-formatter-utils.js

@@ -0,0 +1,69 @@
+import chalk = require('chalk');
+
+interface MessagePrefixData {
+  sender: string;
+  cluster_id?: string | null;
+  sender_model?: string | null;
+}
+
+/**
+ * Get color for sender based on consistent hashing.
+ */
+function getColorForSender(sender: string): chalk.Chalk {
+  const colors = [chalk.cyan, chalk.magenta, chalk.yellow, chalk.green, chalk.blue];
+  let hash = 0;
+  for (let i = 0; i < sender.length; i++) {
+    hash = (hash << 5) - hash + sender.charCodeAt(i);
+    hash = hash & hash;
+  }
+  return colors[Math.abs(hash) % colors.length] ?? chalk.cyan;
+}
+
+/**
+ * Build message prefix with timestamp, sender, and optional cluster ID.
+ */
+function buildMessagePrefix(
+  msg: MessagePrefixData,
+  showClusterId: boolean,
+  isActive: boolean
+): string {
+  const color = isActive ? getColorForSender(msg.sender) : chalk.dim;
+
+  let senderLabel = msg.sender;
+  if (showClusterId && msg.cluster_id) {
+    senderLabel = `${msg.cluster_id}/${msg.sender}`;
+  }
+
+  const modelSuffix = msg.sender_model ? chalk.dim(` [${msg.sender_model}]`) : '';
+  return color(`${senderLabel.padEnd(showClusterId ? 25 : 15)} |`) + modelSuffix;
+}
+
+/**
+ * Build cluster prefix for watch mode.
+ */
+function buildClusterPrefix(clusterId: string, isActive: boolean): string {
+  const color = isActive ? chalk.white : chalk.dim;
+  return color(`${clusterId.padEnd(20)} |`);
+}
+
+/**
+ * Parse and normalize data fields (handles string JSON).
+ */
+function parseDataField(data: unknown): unknown {
+  if (typeof data === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(data);
+      return parsed;
+    } catch {
+      return [];
+    }
+  }
+  return Array.isArray(data) ? data : [];
+}
+
+export = {
+  getColorForSender,
+  buildMessagePrefix,
+  buildClusterPrefix,
+  parseDataField,
+};

cli/message-formatter-utils.ts

@@ -355,6 +355,8 @@ export default [
       'lib/cluster/**',
       'lib/hosted-session/**',
       'lib/target/**',
+      'cli/event-copy.js',
+      'cli/message-formatter-utils.js',
       'lib/clusters-registry.js',
       'lib/completion.js',
       'lib/compose-utils.js',
@@ -392,6 +394,11 @@ export default [
       'lib/start-cluster.js',
       'lib/stream-json-parser.js',
       'src/guidance-topics.js',
+      'src/input-helpers.js',
+      'src/ledger-sequence.js',
+      'src/message-buffer.js',
+      'src/task-startup-error.js',
+      'src/task-runner.js',
       'src/omp-blob-root.js',
       'src/omp-config-overlay.js',
       'task-lib/completion.js',
@@ -406,11 +413,13 @@ export default [
       'src/agent/provider-control-plane.js',
       'src/agent/structured-output-error.js',
       'src/agent/validation-platform.js',
+      'src/attach/socket-paths.js',
       'src/providers/anthropic/index.js',
       'src/providers/capabilities.js',
       'src/providers/google/index.js',
       'src/providers/openai/index.js',
       'src/providers/opencode/index.js',
+      'src/template-validation/report-formatter.js',
     ],
   },
   prettierConfig,

eslint.config.mjs

@@ -1,42 +1,34 @@
-/**
- * Deterministic attach socket paths.
- *
- * Unix-domain sockets have a small path budget (104 bytes on macOS). Keep the
- * live socket namespace independent from HOME while retaining one namespace
- * per OS user and Zeroshot home.
- */
-
-const crypto = require('crypto');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
+import crypto = require('crypto');
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
 
 const SOCKET_ROOT = process.platform === 'win32' ? null : '/tmp';
 const SOCKET_DIR_MODE = 0o700;
 
-function shortHash(value) {
+function shortHash(value: string): string {
   return crypto.createHash('sha256').update(value).digest('hex').slice(0, 16);
 }
 
-function userNamespace() {
+function userNamespace(): string {
   if (typeof process.getuid === 'function') {
     return String(process.getuid());
   }
   return shortHash(os.userInfo().username);
 }
 
-function resolveHomeDir(env = process.env) {
+function resolveHomeDir(env: NodeJS.ProcessEnv = process.env): string {
   return env.ZEROSHOT_HOME || env.HOME || env.USERPROFILE || os.homedir();
 }
 
-function getSocketDir(homeDir = resolveHomeDir()) {
-  if (process.platform === 'win32') {
+function getSocketDir(homeDir = resolveHomeDir()): string {
+  if (SOCKET_ROOT === null) {
     return path.join(homeDir, '.zeroshot', 'sockets');
   }
   return path.join(SOCKET_ROOT, `zeroshot-${userNamespace()}-${shortHash(homeDir)}`);
 }
 
-function assertSafeSocketDir(socketDir) {
+function assertSafeSocketDir(socketDir: string): void {
   const stat = fs.lstatSync(socketDir);
   if (!stat.isDirectory() || stat.isSymbolicLink()) {
     throw new Error(`Attach socket path is not a directory: ${socketDir}`);
@@ -46,7 +38,7 @@ function assertSafeSocketDir(socketDir) {
   }
 }
 
-function ensureOwnedDirectory(socketDir) {
+function ensureOwnedDirectory(socketDir: string): string {
   fs.mkdirSync(socketDir, { recursive: true, mode: SOCKET_DIR_MODE });
   assertSafeSocketDir(socketDir);
   if (process.platform !== 'win32') {
@@ -55,26 +47,30 @@ function ensureOwnedDirectory(socketDir) {
   return socketDir;
 }
 
-function ensureSocketDir(homeDir = resolveHomeDir()) {
+function ensureSocketDir(homeDir = resolveHomeDir()): string {
   const socketDir = getSocketDir(homeDir);
   return ensureOwnedDirectory(socketDir);
 }
 
-function getTaskSocketPath(taskId, homeDir = resolveHomeDir()) {
+function getTaskSocketPath(taskId: string, homeDir = resolveHomeDir()): string {
   return path.join(ensureSocketDir(homeDir), `${taskId}.sock`);
 }
 
-function getAgentSocketPath(clusterId, agentId, homeDir = resolveHomeDir()) {
+function getAgentSocketPath(
+  clusterId: string,
+  agentId: string,
+  homeDir = resolveHomeDir()
+): string {
   const clusterDir = path.join(ensureSocketDir(homeDir), clusterId);
   ensureOwnedDirectory(clusterDir);
   return path.join(clusterDir, `${agentId}.sock`);
 }
 
-function getClusterSocketPath(clusterId, homeDir = resolveHomeDir()) {
+function getClusterSocketPath(clusterId: string, homeDir = resolveHomeDir()): string {
   return path.join(ensureSocketDir(homeDir), `${clusterId}.sock`);
 }
 
-module.exports = {
+export = {
   SOCKET_DIR_MODE,
   resolveHomeDir,
   getSocketDir,

src/attach/socket-paths.js src/attach/socket-paths.tssrc/attach/socket-paths.js renamed to src/attach/socket-paths.ts

@@ -1,21 +1,25 @@
+import fs = require('fs');
+import path = require('path');
+
+interface ManualInput {
+  number: null;
+  title: string;
+  body: string;
+  labels: unknown[];
+  comments: unknown[];
+  url: null;
+  context: string;
+}
+
 /**
  * Input Helpers - Create input data from text or files
  *
  * Provides fallback input methods for non-issue-based input:
  * - Plain text input
  * - File input (markdown)
  */
-
-const fs = require('fs');
-const path = require('path');
-
 class InputHelpers {
-  /**
-   * Create a plain text input wrapper
-   * @param {String} text - Plain text input
-   * @returns {Object} Structured context
-   */
-  static createTextInput(text) {
+  static createTextInput(text: string): ManualInput {
     return {
       number: null,
       title: 'Manual Input',
@@ -27,26 +31,15 @@ class InputHelpers {
     };
   }
 
-  /**
-   * Create input from markdown file
-   * @param {String} filePath - Path to markdown file (.md or .markdown)
-   * @returns {Object} Structured context matching issue format
-   */
-  static createFileInput(filePath) {
-    // Resolve relative paths
+  static createFileInput(filePath: string): ManualInput {
     const resolvedPath = path.resolve(filePath);
-
-    // Validate file exists
     if (!fs.existsSync(resolvedPath)) {
       throw new Error(`File not found: ${filePath}`);
     }
 
-    // Read file content
     const fileContent = fs.readFileSync(resolvedPath, 'utf8');
-
-    // Extract title from first header or use filename
-    const headerMatch = fileContent.match(/^#\s+(.+)$/m);
-    const extractedTitle = headerMatch ? headerMatch[1].trim() : null;
+    const headerMatch = /^#\s+(.+)$/m.exec(fileContent);
+    const extractedTitle = headerMatch?.[1]?.trim() ?? null;
     const fallbackTitle = path.basename(filePath, path.extname(filePath));
     const title = extractedTitle || fallbackTitle;
 
@@ -62,4 +55,4 @@ class InputHelpers {
   }
 }
 
-module.exports = InputHelpers;
+export = InputHelpers;