boxsafe 1.0.0

package/core/loop/execLoop.ts

@@ -0,0 +1,341 @@
+/**
+ * @fileoverview
+ * Implements an iterative agent loop that coordinates LLM code generation,
+ * execution, and validation until a successful result is achieved.
+ *
+ * @description
+ * The loop follows a deterministic pipeline:
+ * 1. Send feedback to an LLM instance.
+ * 2. Read the generated markdown artifact.
+ * 3. Extract language-specific code blocks.
+ * 4. Write the extracted code to an output file.
+ * 5. Execute the output via a system command.
+ * 6. Validate execution results using a waterfall validator.
+ * 7. Generate structured feedback on failure and retry.
+ *
+ * The process repeats until validation succeeds.
+ *
+ * This module is designed for automated agent workflows.
+ * Logs and artifacts are intended for machine consumption, not humans.
+ *
+ * @module core/loop
+ */
+
+import { readFile } from "node:fs/promises";
+import { pathToCode } from "@core/paths/paths";
+import { createLLM } from "@ai/provider";
+import { runLLM } from "@ai/caller";
+import { LService, LModel } from "@ai/label";
+import { extractCode } from "../../util/extractCode";
+import type { CommandRun } from "../../types";
+import { execode } from "./cmd/execode";
+import { ANSI } from "@util/ANSI";
+import { createNavigator } from "@core/navigate";
+import type { Navigator } from "@core/navigate";
+import TasksManager from '@core/loop/tasks';
+import { loadBoxConfig, getVersionControlFlags } from '@core/loop/boxConfig';
+import { createVersionControlAttemptRunner } from '@core/loop/versionControlAdapter';
+import { dispatchToolCalls } from '@core/loop/toolDispatcher';
+import { initTasksManager } from '@core/loop/initTasksManager';
+import { initNavigator } from '@core/loop/initNavigator';
+import { writeArtifactAtomically } from '@core/loop/writeArtifactAtomically';
+import { buildExecCommand } from '@core/loop/buildExecCommand';
+import { runValidation } from '@core/loop/runValidation';
+import type { LoopOptions, LoopResult } from '@core/loop/types';
+import { createTraceLogger } from '@core/loop/traceLogger';
+
+/**
+ * Create a navigator instance with the given workspace.
+ * Useful for creating navigator before loop or injecting custom config.
+ * @param workspace - path to workspace directory
+ * @param maxFileSize - optional maximum file size in bytes (default 10MB)
+ * @returns Navigator instance
+ */
+export const createWorkspaceNavigator = (workspace: string, maxFileSize?: number): Navigator => {
+  return createNavigator({
+    workspace,
+    maxFileSize: maxFileSize ?? 10 * 1024 * 1024, // maximum in bytes
+  });
+}; // Summary: Get the working path, adjust it to absolute, and get the maximum size in MB for a file.
+
+// Reads the markdown file generated by the model (path injectable for testability)
+const readMarkdown = async (markdownPath: string) => {
+  return readFile(markdownPath, "utf-8");
+};
+
+export const loop = async (
+  {
+    service,
+    model,
+    initialPrompt,
+    cmd,
+    lang,
+    pathOutput,
+    maxIterations = 10,
+    limit,
+    signal,
+    pathGeneratedMarkdown = pathToCode,
+    navigator: injectedNavigator,
+    workspace,
+  } : LoopOptions
+): Promise<LoopResult> => {
+  const llm = createLLM(service, model);
+  const trace = createTraceLogger({});
+  const log = trace.wrapLogger();
+  await trace.emit('loop.start', { runId: trace.runId }, {
+    service: String(service),
+    model: String(model),
+    lang: String(lang),
+    maxIterations: Number(maxIterations),
+  });
+
+  // Version control: configurable commit messages and behavior
+  // Top-level variable for the 'before' commit message so it's easy to find and change.
+  const BEFORE_COMMIT_MESSAGE = process.env.BOXSAFE_BEFORE_MSG ?? 'save agent';
+
+  const boxConfig = loadBoxConfig();
+  const { vcBefore, vcAfter, vcGenerateNotes, vcAutoPushConfig } = getVersionControlFlags(boxConfig);
+  const attemptVersionControl = createVersionControlAttemptRunner();
+
+  const configuredTimeoutMs = typeof boxConfig.commands?.timeoutMs === 'number' ? boxConfig.commands.timeoutMs : undefined;
+
+  // If configured, run a one-time 'before' commit when the agent starts
+  if (vcBefore) {
+    try {
+      await trace.emit('versionControl.before.start', { runId: trace.runId });
+      const res = await attemptVersionControl({ repoPath: workspace ?? process.cwd(), commitMessage: BEFORE_COMMIT_MESSAGE, autoPush: vcAutoPushConfig, generateNotes: vcGenerateNotes });
+      log.info(`${ANSI.Cyan}[VersionControl]${ANSI.Reset} before-commit completed: ${JSON.stringify(res)}`);
+      await trace.emit('versionControl.before.ok', { runId: trace.runId }, { result: res as any });
+    } catch (err: any) {
+      log.warn(`${ANSI.Yellow}[VersionControl]${ANSI.Reset} before-commit failed after retries: ${err?.message ?? err}`);
+      await trace.emit('versionControl.before.error', { runId: trace.runId }, { error: err?.message ?? String(err) });
+    }
+  }
+
+  const tasksManager: TasksManager | null = await initTasksManager(boxConfig);
+
+  // Determine effective workspace (from arg, config or cwd) and initialize navigator
+  log.info(`${ANSI.Cyan}[InitNavigator]${ANSI.Reset} Initializing navigator...`);
+  const { effectiveWorkspace, navigator } = initNavigator({
+    ...(workspace ? { workspaceArg: workspace } : {}),
+    ...(boxConfig.project?.workspace ? { configWorkspace: boxConfig.project.workspace } : {}),
+    ...(injectedNavigator ? { injectedNavigator } : {}),
+  });
+  
+  log.info(`${ANSI.Cyan}[InitNavigator]${ANSI.Reset} Navigator initialized: ${!!navigator ? 'YES' : 'NO'}, Workspace: ${effectiveWorkspace}`);
+
+  const effectiveLimit = typeof limit === "number" ? limit : maxIterations;
+  // feedback starts from tasks manager current task if available, otherwise initial prompt
+  let feedback = initialPrompt;
+  if (tasksManager && !tasksManager.isFinished()) {
+    const t = tasksManager.getCurrentTask();
+    if (t) feedback = t;
+  }
+
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  for (limit = 1; limit <= effectiveLimit; limit++) {
+    const iterCtx = { runId: trace.runId, iter: limit };
+    const iterLog = trace.wrapLogger(iterCtx);
+    if (signal?.aborted) {
+      iterLog.error(`aborted`);
+      await trace.emit('loop.aborted', iterCtx);
+      return { ok: false, iterations: limit, navigator };
+    }
+
+    iterLog.info(`iteration ${limit}`);
+    await trace.emit('iteration.start', iterCtx);
+
+    // Run the LLM with the current feedback (with a small retry/backoff for transient LLM errors)
+    let llmAttempts = 0;
+    const maxLlmAttempts = 3;
+    while (true) {
+      try {
+        if (signal?.aborted) throw new Error("Aborted");
+        const promptToSend = `${feedback}\n\nYou may optionally emit tool calls as JSON fenced blocks (\`\`\`json-tool ...\`\`\`) BEFORE the final code block. If you do, set tool=\"navigate\" and params.op=\"write\" to create files. Then, ALWAYS end your response with exactly ONE code block in the language: ${lang}`;
+        await trace.emit('llm.run.start', iterCtx);
+        await runLLM(promptToSend, llm, { service, model, outputPath: pathGeneratedMarkdown });
+        await trace.emit('llm.run.ok', iterCtx, { outputPath: pathGeneratedMarkdown });
+        break;
+      } catch (err: any) {
+        llmAttempts++;
+        iterLog.error(`${err?.message ?? err}`);
+        await trace.emit('llm.run.error', iterCtx, { error: err?.message ?? String(err), attempt: llmAttempts });
+        if (llmAttempts >= maxLlmAttempts) {
+          await trace.emit('iteration.failed', iterCtx, { layer: 'llm' });
+          return { ok: false, iterations: limit, navigator };
+        }
+        const backoff = 200 * Math.pow(2, llmAttempts - 1);
+        await sleep(backoff);
+      }
+    }
+
+    // Read the generated markdown
+    let markdown: string;
+    try {
+      if (signal?.aborted) throw new Error("Aborted");
+      markdown = await readMarkdown(pathGeneratedMarkdown);
+      await trace.emit('markdown.read.ok', iterCtx, { path: pathGeneratedMarkdown, bytes: markdown.length });
+    } catch (err: any) {
+      iterLog.error(`${ANSI.Red}[ReadMarkdown]${ANSI.Reset} ${err?.message ?? err}`);
+      await trace.emit('markdown.read.error', iterCtx, { error: err?.message ?? String(err), path: pathGeneratedMarkdown });
+      // give feedback to the model and retry
+      feedback = "Could not read the generated markdown. Please emit markdown artifact.";
+      continue;
+    }
+
+    // Extract code blocks for the target language
+    let codeBlocks: string[];
+    try {
+      if (signal?.aborted) throw new Error("Aborted");
+      codeBlocks = await extractCode(markdown, lang, {
+        throwOnNotFound: true,
+      });
+      await trace.emit('extractCode.ok', iterCtx, { blocks: codeBlocks.length, lang: String(lang) });
+    } catch (err: any) {
+      iterLog.warn(`${ANSI.Yellow}[ExtractCode]${ANSI.Reset} ${err?.message ?? err}`);
+      await trace.emit('extractCode.error', iterCtx, { error: err?.message ?? String(err), lang: String(lang) });
+      feedback = "No code blocks were found. Generate valid code for the requested language.";
+      continue;
+    }
+
+    // --- Tool call handling: detect JSON tool blocks in the generated markdown ---
+    iterLog.info(`${ANSI.Cyan}[ToolCalls]${ANSI.Reset} Processing tool calls from markdown...`);
+    await dispatchToolCalls({
+      markdown,
+      navigator,
+      boxConfig,
+      ANSI,
+      attemptVersionControl,
+      vcAutoPushConfig,
+      traceEmit: trace.emit.bind(trace),
+      traceCtx: iterCtx,
+    });
+    iterLog.info(`${ANSI.Cyan}[ToolCalls]${ANSI.Reset} Tool call processing completed`);
+
+    if (!codeBlocks || codeBlocks.length === 0) {
+      feedback = "No code blocks were found. Generate valid code.";
+      continue;
+    }
+
+    // Atomic write: write to temp and rename
+    const tmpPath = `${pathOutput}.tmp`;
+    try {
+      await writeArtifactAtomically({
+        tmpPath,
+        pathOutput,
+        content: codeBlocks.join("\n\n"),
+        ...(signal ? { signal } : {}),
+      });
+      await trace.emit('artifact.write.ok', iterCtx, { path: pathOutput, bytes: codeBlocks.join("\n\n").length });
+    } catch (err: any) {
+      iterLog.error(`${ANSI.Red}[WriteFile]${ANSI.Reset} ${err?.message ?? err}`);
+      await trace.emit('artifact.write.error', iterCtx, { error: err?.message ?? String(err), path: pathOutput });
+      feedback = "Failed to write output file. Ensure filesystem permissions are correct.";
+      continue;
+    }
+
+    // Execute the generated code
+    let execResult: any;
+    try {
+      if (signal?.aborted) throw new Error("Aborted");
+      const execCmd = await buildExecCommand({ cmd, lang, pathOutput });
+      await trace.emit('exec.start', iterCtx, { cmd: Array.isArray(execCmd) ? execCmd[0] : execCmd });
+      execResult = await execode(execCmd, {
+        ...(configuredTimeoutMs !== undefined ? { timeoutMs: configuredTimeoutMs } : {}),
+      });
+      await trace.emit('exec.ok', iterCtx, { exitCode: execResult.exitCode });
+    } catch (err: any) {
+      iterLog.error(`${ANSI.Red}[Execode]${ANSI.Reset} ${err?.message ?? err}`);
+      await trace.emit('exec.error', iterCtx, { error: err?.message ?? String(err) });
+      feedback = `Execution failed: ${err?.message ?? "unknown"}`;
+      continue;
+    }
+
+    // Debug: log exec output and the written artifact to diagnose failures
+    try {
+      iterLog.info(`${ANSI.Cyan}[Execode]${ANSI.Reset} exit=${execResult.exitCode}`);
+      iterLog.info(`${ANSI.Cyan}[Execode]${ANSI.Reset} stdout=${String(execResult.stdout).slice(0,1000)}`);
+      iterLog.info(`${ANSI.Cyan}[Execode]${ANSI.Reset} stderr=${String(execResult.stderr).slice(0,1000)}`);
+      try {
+        const outFile = await readFile(pathOutput, 'utf-8');
+        iterLog.info(`${ANSI.Cyan}[OutputFile]${ANSI.Reset} ${outFile.slice(0,1000)}`);
+      } catch (err: any) {
+        iterLog.info(`${ANSI.Cyan}[OutputFile]${ANSI.Reset} could not read output file: ${err?.message ?? err}`);
+      }
+    } catch (errAny) {
+      // swallow logging errors
+    }
+
+    // Validate execution results using the waterfall pipeline
+    let verdict: any;
+    try {
+      await trace.emit('validation.start', iterCtx);
+      verdict = await runValidation({
+        execResult,
+        pathOutput,
+        ...(signal ? { signal } : {}),
+      });
+      await trace.emit('validation.ok', iterCtx, {
+        ok: Boolean(verdict?.ok),
+        score: typeof verdict?.score === 'number' ? verdict.score : undefined,
+        layer: verdict?.layer ?? undefined,
+      });
+    } catch (err: any) {
+      await trace.emit('validation.error', iterCtx, { error: err?.message ?? String(err) });
+      feedback = `Validation pipeline failed: ${err?.message ?? "unknown"}`;
+      continue;
+    }
+
+    // Stop or advance if the execution is valid
+    if (verdict?.ok) {
+      iterLog.info(`success for current task/iteration`);
+      await trace.emit('iteration.success', iterCtx, {
+        score: typeof verdict?.score === 'number' ? verdict.score : undefined,
+      });
+
+      // If task manager is active, mark current done and continue to next
+      if (tasksManager) {
+        await tasksManager.markCurrentDone();
+        if (!tasksManager.isFinished()) {
+          const next = tasksManager.getCurrentTask();
+          feedback = next ?? feedback;
+          log.info(`${ANSI.Cyan}[Tasks]${ANSI.Reset} advanced to next task`);
+          // continue loop to process next task
+          continue;
+        }
+        // all tasks done — proceed to after-success flow below
+        log.info(`${ANSI.Cyan}[Tasks]${ANSI.Reset} all tasks completed`);
+      }
+
+      // After-success versioning (commit explaining what was done)
+      if (vcAfter) {
+        const afterMessage = `agent: completed successfully in ${limit} iterations`;
+        try {
+          await trace.emit('versionControl.after.start', iterCtx);
+          const res = await attemptVersionControl({ repoPath: workspace ?? process.cwd(), commitMessage: afterMessage, autoPush: vcAutoPushConfig, generateNotes: vcGenerateNotes });
+          log.info(`${ANSI.Cyan}[VersionControl]${ANSI.Reset} after-commit completed: ${JSON.stringify(res)}`);
+          await trace.emit('versionControl.after.ok', iterCtx, { result: res as any });
+        } catch (err: any) {
+          log.warn(`${ANSI.Yellow}[VersionControl]${ANSI.Reset} after-commit failed after retries: ${err?.message ?? err}`);
+          await trace.emit('versionControl.after.error', iterCtx, { error: err?.message ?? String(err) });
+        }
+      }
+
+      return { ok: true, iterations: limit, verdict, artifacts: { outputFile: pathOutput }, navigator };
+    }
+
+    // Build structured feedback for the next iteration
+    feedback = `Layer: ${verdict?.layer ?? "unknown"}\nReason: ${verdict?.reason ?? "unknown"}\nDetails: ${verdict?.details ?? "n/a"}`;
+
+    iterLog.warn(`${ANSI.Yellow}[Waterfall]${ANSI.Reset} failed at ${verdict?.layer ?? "unknown"}`);
+    await trace.emit('iteration.failed', iterCtx, {
+      layer: verdict?.layer ?? 'unknown',
+      reason: verdict?.reason ?? 'unknown',
+      score: typeof verdict?.score === 'number' ? verdict.score : undefined,
+    });
+  }
+
+  // If the loop completes without a successful verdict
+  return { ok: false, iterations: limit, navigator };
+};

package/core/loop/git/VERSIONING.md

@@ -0,0 +1,17 @@
+# Git Versioning Module
+
+Purpose
+- Lightweight helper for staging, committing and optionally pushing changes to Git/GitHub.
+
+Behavior
+- Finds repository root (searches up from working directory)
+- Stages all changes and commits with a sensible default message
+- Optionally creates `BOXSAFE_VERSION_NOTES.md` describing the commit
+- Attempts to push to `origin` and will try a token from keyring (`gh-token`) or `PASSWORD_GIT` env var if push fails due to auth
+
+How to use
+- Programmatic: import `runVersionControl` from `@core/loop/git` and call with options `{ autoPush?: boolean, generateNotes?: boolean, commitMessage?: string }`.
+- CLI / manual: this module is intended to be invoked by the agent runtime.
+
+Security
+- Token injection only used as a fallback for a single push attempt. Prefer using native credential helpers or keyring (see `core/auth/dasktop/cred`).

package/core/loop/git/commands.ts

@@ -0,0 +1,11 @@
+// Centralized git command templates for easy maintenance
+export const GIT_STATUS = 'git status --porcelain';
+export const GIT_ADD_ALL = 'git add -A';
+export const GIT_GET_BRANCH = 'git rev-parse --abbrev-ref HEAD';
+export const GIT_REMOTE_GET_URL = 'git remote get-url origin';
+export const GIT_SHOW_COMMIT = 'git show --name-only --pretty=format:"%B" HEAD';
+
+export const gitCommitCmd = (message: string) => `git commit -m "${String(message).replace(/"/g, '\\"')}"`;
+export const gitPushOriginCmd = (branch?: string) => branch ? `git push origin ${branch}` : 'git push origin HEAD';
+export const gitPushSetUpstreamCmd = (branch: string) => `git push --set-upstream origin ${branch}`;
+export const gitPushToUrlCmd = (remoteUrl: string, branch: string) => `git push "${remoteUrl}" HEAD:refs/heads/${branch}`;

package/core/loop/git/gitClient.ts

@@ -0,0 +1,78 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'node:path';
+import {
+  GIT_STATUS,
+  GIT_ADD_ALL,
+  GIT_GET_BRANCH,
+  GIT_REMOTE_GET_URL,
+  GIT_SHOW_COMMIT,
+  gitCommitCmd,
+  gitPushOriginCmd,
+  gitPushSetUpstreamCmd,
+  gitPushToUrlCmd,
+} from './commands';
+
+const execAsync = promisify(exec);
+
+export async function runCommand(cmd: string, cwd?: string) {
+  try {
+    const res = await execAsync(cmd, { cwd, env: process.env });
+    return { stdout: res.stdout?.toString() ?? '', stderr: res.stderr?.toString() ?? '', code: 0 };
+  } catch (err: any) {
+    return { stdout: err.stdout?.toString() ?? '', stderr: err.stderr?.toString() ?? err.message, code: err.code ?? 1 };
+  }
+}
+
+export async function hasUnstagedChanges(repoPath: string) {
+  const r = await runCommand(GIT_STATUS, repoPath);
+  return (r.stdout || r.stderr).trim().length > 0;
+}
+
+export async function stageAll(repoPath: string) {
+  return runCommand(GIT_ADD_ALL, repoPath);
+}
+
+export async function commitAll(repoPath: string, message = 'chore: alterações automáticas do agente') {
+  const status = await hasUnstagedChanges(repoPath);
+  if (!status) return { ok: false, reason: 'no-changes' };
+  const r = await runCommand(gitCommitCmd(message), repoPath);
+  return { ok: r.code === 0, out: r.stdout, err: r.stderr };
+}
+
+export async function getRemoteUrl(repoPath: string) {
+  const r = await runCommand(GIT_REMOTE_GET_URL, repoPath);
+  if (r.code !== 0) return null;
+  return (r.stdout || '').trim();
+}
+
+export function injectTokenInHttpsUrl(remoteUrl: string, token: string) {
+  if (!remoteUrl.startsWith('https://')) return null;
+  // https://github.com/owner/repo.git -> https://{token}@github.com/owner/repo.git
+  const withoutProto = remoteUrl.replace('https://', '');
+  return `https://${encodeURIComponent(token)}@${withoutProto}`;
+}
+
+export async function pushOrigin(repoPath: string) {
+  // prefer explicit branch push to allow clearer error handling upstream
+  const branchRes = await runCommand(GIT_GET_BRANCH, repoPath);
+  const branch = (branchRes.stdout || '').trim() || 'HEAD';
+  return runCommand(gitPushOriginCmd(branch), repoPath);
+}
+
+export async function pushWithToken(remoteUrl: string, repoPath: string, token: string) {
+  const injected = injectTokenInHttpsUrl(remoteUrl, token);
+  if (!injected) return { code: 1, stderr: 'remote-not-https' };
+  // get current branch
+  const branchRes = await runCommand(GIT_GET_BRANCH, repoPath);
+  const branch = (branchRes.stdout || '').trim();
+  if (!branch) return { code: 1, stderr: 'could-not-detect-branch' };
+  const cmd = gitPushToUrlCmd(injected, branch);
+  return runCommand(cmd, repoPath);
+}
+
+export async function getCommitSummary(repoPath: string) {
+  const r = await runCommand(GIT_SHOW_COMMIT, repoPath);
+  if (r.code !== 0) return null;
+  return r.stdout.trim();
+}

package/core/loop/git/index.ts

@@ -0,0 +1,99 @@
+/**
+ * GitHub versioning helper
+ * - stages and commits changes
+ * - optionally generates notes
+ * - attempts push; falls back to keyring token when available
+ *
+ * Design goals: minimal, robust, descriptive names and clear behavior.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { runCommand, stageAll, commitAll, getRemoteUrl, pushOrigin, pushWithToken, getCommitSummary } from './gitClient';
+import { getCredLinux } from '@core/auth/dasktop/cred/credLinux';
+
+async function findRepoRoot(start = process.cwd()) {
+  let cur = start;
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(cur, '.git'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return start; // fallback
+}
+
+export interface VersionControlOptions {
+  repoPath?: string;
+  commitMessage?: string;
+  autoPush?: boolean;
+  generateNotes?: boolean;
+}
+
+export async function runVersionControl(opts: VersionControlOptions = {}) {
+  const repoRoot = opts.repoPath ? path.resolve(opts.repoPath) : await findRepoRoot();
+  const message = opts.commitMessage ?? 'chore: alterações automáticas do agente';
+
+  // ensure git user config exists (if not, use EMAIL_GIT env var)
+  const emailCheck = await runCommand('git config user.email', repoRoot);
+  if (!emailCheck.stdout?.trim() && process.env.EMAIL_GIT) {
+    await runCommand(`git config user.email "${process.env.EMAIL_GIT}"`, repoRoot);
+  }
+
+  // Stage and commit
+  await stageAll(repoRoot);
+  const commitResult = await commitAll(repoRoot, message);
+  if (!commitResult.ok && commitResult.reason === 'no-changes') {
+    return { committed: false, reason: 'no-changes' };
+  }
+
+  // Optionally generate notes
+  if (opts.generateNotes || process.env.BOXSAFE_GENERATE_NOTES === '1') {
+    const summary = (await getCommitSummary(repoRoot)) ?? '';
+    const notesPath = path.join(repoRoot, 'BOXSAFE_VERSION_NOTES.md');
+    const notes = `# BOXSAFE Versioning Notes\n\nCommit message:\n\n${message}\n\nSummary:\n\n${summary}\n`;
+    try {
+      fs.writeFileSync(notesPath, notes, { encoding: 'utf-8' });
+      await runCommand(`git add "${notesPath}"`, repoRoot);
+      await runCommand(`git commit -m "chore: add versioning notes by boxsafe agent"`, repoRoot);
+    } catch (err) {
+      // ignore note failures
+    }
+  }
+
+  // Attempt push if requested
+  if (opts.autoPush) {
+    const remote = await getRemoteUrl(repoRoot);
+    if (!remote) return { committed: true, pushed: false, reason: 'no-remote' };
+
+    // try to push normally first
+    const pushResp = await pushOrigin(repoRoot);
+    if (pushResp.code === 0) return { committed: true, pushed: true };
+
+    // If push failed, attempt to detect branch/upstream issues and retry with set-upstream
+    const branchRes = await runCommand('git rev-parse --abbrev-ref HEAD', repoRoot);
+    const branch = (branchRes.stdout || '').trim();
+    const stderr = String(pushResp.stderr || '').toLowerCase();
+
+    const needsSetUpstream = /no upstream|set upstream|no tracking information|failed to push some refs/.test(stderr) && branch;
+    if (needsSetUpstream) {
+      try {
+        const setRes = await runCommand(`git push --set-upstream origin ${branch}`, repoRoot);
+        if (setRes.code === 0) return { committed: true, pushed: true, note: 'set-upstream' };
+      } catch (e) {
+        // swallow and fall through to token fallback
+      }
+    }
+
+    // If push failed (likely auth), try token from keyring or env
+    const token = (await getCredLinux({ account: 'gh-token' })) ?? process.env.PASSWORD_GIT ?? process.env.GITHUB_TOKEN;
+    if (!token) return { committed: true, pushed: false, reason: 'auth-needed', pushStdErr: pushResp.stderr };
+
+    const tryPushWithToken = await pushWithToken(remote, repoRoot, token);
+    if (tryPushWithToken.code === 0) return { committed: true, pushed: true, note: 'pushed-with-token' };
+    return { committed: true, pushed: false, reason: 'push-failed', pushStdErr: String(tryPushWithToken.stderr || tryPushWithToken.stderr) };
+  }
+
+  return { committed: true, pushed: false };
+}
+
+export default { runVersionControl };

package/core/loop/git/runVersionControlRunner.ts

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import { runVersionControl } from '@core/loop/git';
+import { Logger } from '@core/util/logger';
+
+dotenv.config({ path: path.resolve(process.cwd(), '.env') });
+
+const logger = Logger.createModuleLogger('VersionControlRunner');
+
+async function main() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const repoRoot = path.resolve(__dirname, '../../../');
+
+  const configPath = path.join(repoRoot, 'boxsafe.config.json');
+  let bsConfig: any = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      bsConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch (err) {
+      bsConfig = {};
+    }
+  }
+
+  const autoPush = bsConfig.project?.versionControl?.after ?? (process.env.BOXSAFE_AUTO_PUSH === '1');
+  const generateNotes = bsConfig.project?.versionControl?.generateNotes ?? (process.env.BOXSAFE_GENERATE_NOTES === '1');
+
+  const res = await runVersionControl({ repoPath: repoRoot, autoPush, generateNotes, commitMessage: 'chore: add git versioning module (boxsafe agent)' });
+  logger.info(`Version control result: ${JSON.stringify(res)}`);
+}
+
+main().catch((e) => { logger.error(`Runner error: ${e}`); process.exit(1); });

package/core/loop/initNavigator.ts

@@ -0,0 +1,44 @@
+import { createNavigator } from '@core/navigate';
+import type { Navigator } from '@core/navigate';
+import { Logger } from '@core/util/logger';
+
+const logger = Logger.createModuleLogger('InitNavigator');
+
+type InitNavigatorArgs = {
+  workspaceArg?: string;
+  configWorkspace?: string;
+  injectedNavigator?: Navigator;
+};
+
+export function initNavigator({ workspaceArg, configWorkspace, injectedNavigator }: InitNavigatorArgs): {
+  effectiveWorkspace: string;
+  navigator: Navigator | null;
+} {
+  const effectiveWorkspace = workspaceArg ?? configWorkspace ?? process.cwd();
+  
+  logger.info(`Initializing navigator with workspace: ${effectiveWorkspace}`);
+  logger.debug(`Workspace sources - Arg: ${workspaceArg}, Config: ${configWorkspace}, CWD: ${process.cwd()}`);
+  
+  if (injectedNavigator) {
+    logger.info('Using injected navigator');
+    return { effectiveWorkspace, navigator: injectedNavigator };
+  }
+  
+  if (!effectiveWorkspace) {
+    logger.error('No workspace available for navigator');
+    return { effectiveWorkspace: process.cwd(), navigator: null };
+  }
+  
+  try {
+    const navigator = createNavigator({ 
+      workspace: effectiveWorkspace,
+      logger: Logger.createModuleLogger('Navigator')
+    });
+    
+    logger.info(`Navigator created successfully for workspace: ${effectiveWorkspace}`);
+    return { effectiveWorkspace, navigator };
+  } catch (error) {
+    logger.error(`Failed to create navigator: ${error}`);
+    return { effectiveWorkspace: process.cwd(), navigator: null };
+  }
+}

package/core/loop/initTasksManager.ts

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import TasksManager from './tasks';
+import { TASKS_STATE_DIR } from '@core/paths/paths';
+import { Logger } from '@core/util/logger';
+
+const logger = Logger.createModuleLogger('InitTasksManager');
+
+export async function initTasksManager(boxConfig: any): Promise<TasksManager | null> {
+  let tasksManager: TasksManager | null = null;
+  try {
+    const disableTasks = String(process.env.BOXSAFE_DISABLE_TASKS ?? '').toLowerCase();
+    if (disableTasks === 'true' || disableTasks === '1' || disableTasks === 'yes') {
+      logger.info(`tasks manager disabled by BOXSAFE_DISABLE_TASKS`);
+      return null;
+    }
+
+    const todoCfg = boxConfig.project?.todo ? String(boxConfig.project?.todo).trim() : '';
+    if (todoCfg) {
+      const todoPath = path.resolve(todoCfg);
+      if (fs.existsSync(todoPath) && fs.statSync(todoPath).isFile()) {
+        tasksManager = new TasksManager(todoPath, TASKS_STATE_DIR);
+        await tasksManager.init();
+        logger.info(`loaded ${tasksManager.total()} tasks`);
+      } else {
+        logger.info(`todo path not found or not a file: ${todoCfg}`);
+      }
+    }
+  } catch (error) {
+    logger.warn(`failed to init tasks: ${error}`);
+    tasksManager = null;
+  }
+
+  return tasksManager;
+}