vibeflow-cli 0.1.1 → 0.1.3

package/index.js

@@ -35,9 +35,10 @@ const getDataDir = () => {
   return path.join(xdg, "vibeflow-cli");
 };
 
-const DATA_DIR = getDataDir();
-const SESSIONS_FILE = path.join(DATA_DIR, "sessions.json");
-const STATE_FILE = path.join(DATA_DIR, "state.json");
+const DATA_DIR = getDataDir();
+const SESSIONS_FILE = path.join(DATA_DIR, "sessions.json");
+const STATE_FILE = path.join(DATA_DIR, "state.json");
+const DEFAULT_IDLE_MINUTES = 240;
 
 const ensureDir = () => {
   fs.mkdirSync(DATA_DIR, { recursive: true });
@@ -69,15 +70,49 @@ const saveSessions = (sessions) => {
   saveJson(SESSIONS_FILE, sessions);
 };
 
-const loadState = () => {
-  const data = loadJson(STATE_FILE, { activeByRepo: {} });
-  if (!data || typeof data !== "object") {
-    return { activeByRepo: {} };
-  }
-  return {
-    activeByRepo: data.activeByRepo || {}
-  };
-};
+const loadState = () => {
+  const data = loadJson(STATE_FILE, {
+    activeByRepo: {},
+    idleTimeoutMinutes: DEFAULT_IDLE_MINUTES,
+    pendingTimeEchoesByRepo: {},
+    deliveredTimeEchoesByRepo: {},
+    repoParkedThoughtsByRepo: {}
+  });
+  if (!data || typeof data !== "object") {
+    return {
+      activeByRepo: {},
+      idleTimeoutMinutes: DEFAULT_IDLE_MINUTES,
+      pendingTimeEchoesByRepo: {},
+      deliveredTimeEchoesByRepo: {},
+      repoParkedThoughtsByRepo: {}
+    };
+  }
+  const pending = data.pendingTimeEchoesByRepo || {};
+  const delivered = data.deliveredTimeEchoesByRepo || {};
+  const parked = data.repoParkedThoughtsByRepo || {};
+  const normalizeEchoMap = (map) =>
+    Object.fromEntries(
+      Object.entries(map).map(([key, list]) => [
+        key,
+        Array.isArray(list) ? list.map(normalizeTimeEcho) : []
+      ])
+    );
+  const normalizeThoughtMap = (map) =>
+    Object.fromEntries(
+      Object.entries(map).map(([key, list]) => [
+        key,
+        Array.isArray(list) ? list.map(normalizeParkedThought) : []
+      ])
+    );
+  return {
+    activeByRepo: data.activeByRepo || {},
+    idleTimeoutMinutes:
+      typeof data.idleTimeoutMinutes === "number" ? data.idleTimeoutMinutes : DEFAULT_IDLE_MINUTES,
+    pendingTimeEchoesByRepo: normalizeEchoMap(pending),
+    deliveredTimeEchoesByRepo: normalizeEchoMap(delivered),
+    repoParkedThoughtsByRepo: normalizeThoughtMap(parked)
+  };
+};
 
 const saveState = (state) => {
   saveJson(STATE_FILE, state);
@@ -154,15 +189,32 @@ const renderBigTime = (text) => {
   return lines.map((line) => line.trimEnd());
 };
 
-const formatTime = (iso) => {
-  try {
-    return new Date(iso).toLocaleString();
-  } catch {
-    return iso;
-  }
-};
-
-const findSessionById = (sessions, id) => sessions.find((s) => s.id === id);
+const formatTime = (iso) => {
+  try {
+    return new Date(iso).toLocaleString();
+  } catch {
+    return iso;
+  }
+};
+
+const createId = () => `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const normalizeParkedThought = (thought) => ({
+  id: thought?.id || createId(),
+  text: thought?.text || "",
+  createdAt: thought?.createdAt || nowIso()
+});
+
+const normalizeTimeEcho = (echo) => ({
+  id: echo?.id || createId(),
+  text: echo?.text || "",
+  createdAt: echo?.createdAt || nowIso(),
+  deliverAt: echo?.deliverAt || nowIso(),
+  deliveredAt: echo?.deliveredAt,
+  sourceSessionId: echo?.sourceSessionId
+});
+
+const findSessionById = (sessions, id) => sessions.find((s) => s.id === id);
 
 const getLastSessionForRepo = (sessions, repoKey) => {
   const filtered = sessions.filter((s) => s.repoKey === repoKey);
@@ -173,73 +225,236 @@ const getLastSessionForRepo = (sessions, repoKey) => {
   return filtered[0];
 };
 
-const usage = () => {
-  console.log(`
-VibeFlow CLI
-
-Usage:
-  vf start [path]        Start a session
-  vf intent "text"       Set intent for current repo session
-  vf park "note"         Park a thought
-  vf status              Show current session status
+const usage = () => {
+  console.log(`
+VibeFlow CLI
+
+Usage:
+  vf start [path]        Start a session
+  vf intent "text"       Set intent for current repo session
+  vf park "note"         Park a thought
+  vf echo "message"      Queue a time echo for next session
+  vf echo list           List queued/delivered echoes
+  vf echo park <id>      Park a delivered echo
+  vf echo discard <id>   Discard a delivered echo
+  vf status              Show current session status
   vf status --watch      Live session timer
   vf timer               Live session timer (alias)
-  vf resume [path]       Show last session summary
-  vf history [path]      List recent sessions
+  vf idle [value]        Get/set idle timeout (minutes or Nh)
+  vf touch               Refresh activity timestamp
+  vf resume [path]       Show last session summary
+  vf history [path]      List recent sessions
   vf end                 End current session
   vf receipt [id]        Print receipt (defaults to last session)
-  vf help                Show this help
-`);
-};
+  vf help                Show this help
+`);
+};
 
-const printSessionSummary = (session, active = false) => {
-  const durationMs = session.endedAt
-    ? Date.parse(session.endedAt) - Date.parse(session.startedAt)
-    : Date.now() - Date.parse(session.startedAt);
-  const state = active ? "Active" : session.endedAt ? "Ended" : "In progress";
+const printSessionSummary = (session, active = false) => {
+  const durationMs = session.endedAt
+    ? Date.parse(session.endedAt) - Date.parse(session.startedAt)
+    : Date.now() - Date.parse(session.startedAt);
+  const state = active ? "Active" : session.endedAt ? "Ended" : "In progress";
   console.log(`Repo: ${session.repoName || path.basename(session.repoKey)}`);
   console.log(`Session ID: ${session.id}`);
   console.log(`Status: ${state}`);
-  console.log(`Started: ${formatTime(session.startedAt)}`);
-  if (session.endedAt) {
-    console.log(`Ended: ${formatTime(session.endedAt)}`);
-  }
-  console.log(`Duration: ${formatDuration(durationMs)}`);
-  console.log(`Intent: ${session.intent?.text || "Not set"}`);
-  console.log(`Parked: ${session.parkedThoughts.length}`);
-};
+  console.log(`Started: ${formatTime(session.startedAt)}`);
+  if (session.endedAt) {
+    console.log(`Ended: ${formatTime(session.endedAt)}`);
+  }
+  console.log(`Duration: ${formatDuration(durationMs)}`);
+  console.log(`Intent: ${session.intent?.text || "Not set"}`);
+  console.log(`Parked: ${(session.parkedThoughts || []).length}`);
+  console.log(`Time Echoes: ${(session.timeEchoes || []).length}`);
+};
 
-const ensureActiveSession = (sessions, state, repoKey) => {
-  const activeId = state.activeByRepo[repoKey];
-  if (!activeId) {
-    return null;
-  }
-  const session = findSessionById(sessions, activeId);
-  return session || null;
-};
+const getIdleTimeoutMs = (state) => {
+  const minutes =
+    typeof state.idleTimeoutMinutes === "number" ? state.idleTimeoutMinutes : DEFAULT_IDLE_MINUTES;
+  if (minutes <= 0) {
+    return 0;
+  }
+  return minutes * 60 * 1000;
+};
+
+const normalizeSession = (session) => {
+  if (!session.lastActivityAt) {
+    session.lastActivityAt = session.startedAt;
+  }
+  if (!session.parkedThoughts) {
+    session.parkedThoughts = [];
+  }
+  session.parkedThoughts = session.parkedThoughts.map(normalizeParkedThought);
+  if (!session.timeEchoes) {
+    session.timeEchoes = session.timeEcho ? [normalizeTimeEcho(session.timeEcho)] : [];
+  } else {
+    session.timeEchoes = session.timeEchoes.map(normalizeTimeEcho);
+  }
+  return session;
+};
+
+const ensureGitignore = (repoKey) => {
+  const gitDir = path.join(repoKey, ".git");
+  if (!fs.existsSync(gitDir)) {
+    return;
+  }
+  const gitignorePath = path.join(repoKey, ".gitignore");
+  const entry = ".vibeflow/";
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, `${entry}\n`, "utf8");
+    return;
+  }
+  const raw = fs.readFileSync(gitignorePath, "utf8");
+  const lines = raw.split(/\r?\n/);
+  if (lines.some((line) => line.trim() === entry || line.trim() === ".vibeflow")) {
+    return;
+  }
+  lines.push(entry);
+  fs.writeFileSync(gitignorePath, `${lines.join("\n").replace(/\n+$/, "")}\n`, "utf8");
+};
+
+const buildTracePayload = (session) => {
+  const durationMs = session.endedAt
+    ? Date.parse(session.endedAt) - Date.parse(session.startedAt)
+    : Date.now() - Date.parse(session.startedAt);
+  return {
+    version: 1,
+    generatedAt: nowIso(),
+    sessionId: session.id,
+    repoKey: session.repoKey,
+    repoName: session.repoName,
+    startedAt: session.startedAt,
+    endedAt: session.endedAt || null,
+    durationMs,
+    intent: session.intent || null,
+    parkedThoughts: session.parkedThoughts || [],
+    timeEchoes: session.timeEchoes || []
+  };
+};
+
+const writeTrace = (session) => {
+  try {
+    const dir = path.join(session.repoKey, ".vibeflow");
+    fs.mkdirSync(dir, { recursive: true });
+    const payload = buildTracePayload(session);
+    fs.writeFileSync(path.join(dir, "trace.json"), JSON.stringify(payload, null, 2), "utf8");
+    ensureGitignore(session.repoKey);
+  } catch {
+    // ignore trace failures
+  }
+};
+
+const readTrace = (repoKey) => {
+  try {
+    const filePath = path.join(repoKey, ".vibeflow", "trace.json");
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+const queueTimeEchoes = (session, state) => {
+  if (!session.timeEchoes || session.timeEchoes.length === 0) {
+    return;
+  }
+  const existing = state.pendingTimeEchoesByRepo[session.repoKey] || [];
+  state.pendingTimeEchoesByRepo[session.repoKey] = existing.concat(session.timeEchoes);
+};
+
+const deliverPendingEchoes = (repoKey, state) => {
+  const pending = state.pendingTimeEchoesByRepo[repoKey] || [];
+  if (pending.length === 0) {
+    return [];
+  }
+  delete state.pendingTimeEchoesByRepo[repoKey];
+  state.deliveredTimeEchoesByRepo[repoKey] = pending;
+  return pending;
+};
+
+const clearDeliveredEchoes = (repoKey, state) => {
+  if (state.deliveredTimeEchoesByRepo[repoKey]) {
+    delete state.deliveredTimeEchoesByRepo[repoKey];
+  }
+};
+
+const showEchoes = (echoes) => {
+  if (!echoes || echoes.length === 0) {
+    return;
+  }
+  console.log(c.magenta("Time Echoes:"));
+  echoes.forEach((echo) => {
+    console.log(`- ${echo.id}: ${echo.text}`);
+  });
+  console.log(c.gray("Use `vf echo park <id>` to park or `vf echo discard <id>` to delete."));
+};
+
+const showTraceSummary = (trace) => {
+  if (!trace) {
+    return;
+  }
+  console.log(c.blue("VibeTrace found"));
+  console.log(`Last intent: ${trace.intent?.text || "Not set"}`);
+  if (trace.durationMs) {
+    console.log(`Last session duration: ${formatDuration(trace.durationMs)}`);
+  }
+  console.log(`Parked thoughts: ${(trace.parkedThoughts || []).length}`);
+  console.log(`Time echoes: ${(trace.timeEchoes || []).length}`);
+};
+
+const ensureActiveSession = (sessions, state, repoKey) => {
+  const activeId = state.activeByRepo[repoKey];
+  if (!activeId) {
+    return { session: null, autoEnded: false, endedSession: null };
+  }
+  const session = findSessionById(sessions, activeId);
+  if (!session) {
+    return { session: null, autoEnded: false, endedSession: null };
+  }
+  normalizeSession(session);
+  const timeoutMs = getIdleTimeoutMs(state);
+  if (timeoutMs > 0) {
+    const last = Date.parse(session.lastActivityAt || session.startedAt);
+    if (Date.now() - last > timeoutMs) {
+      session.endedAt = nowIso();
+      session.endedReason = "idle";
+      queueTimeEchoes(session, state);
+      writeTrace(session);
+      saveSessions(sessions);
+      delete state.activeByRepo[repoKey];
+      saveState(state);
+      return { session: null, autoEnded: true, endedSession: session };
+    }
+  }
+  return { session, autoEnded: false, endedSession: null };
+};
 
-const startSession = (targetPath) => {
-  const cwd = targetPath ? path.resolve(targetPath) : process.cwd();
-  const repoKey = getRepoKey(cwd);
-  const repoName = path.basename(repoKey);
-  const sessions = loadSessions();
-  const state = loadState();
-
-  const existing = ensureActiveSession(sessions, state, repoKey);
-  if (existing && !existing.endedAt) {
-    console.log(c.yellow("Session already active:"));
-    printSessionSummary(existing, true);
-    return;
-  }
+const startSession = (targetPath, watch) => {
+  const cwd = targetPath ? path.resolve(targetPath) : process.cwd();
+  const repoKey = getRepoKey(cwd);
+  const repoName = path.basename(repoKey);
+  const sessions = loadSessions();
+  const state = loadState();
+
+  const existing = ensureActiveSession(sessions, state, repoKey);
+  if (existing.session && !existing.session.endedAt) {
+    console.log(c.yellow("Session already active:"));
+    printSessionSummary(existing.session, true);
+    return;
+  }
 
-  const session = {
-    id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
-    repoKey,
-    repoName,
-    cwd,
-    startedAt: nowIso(),
-    parkedThoughts: []
-  };
+  const session = {
+    id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    repoKey,
+    repoName,
+    cwd,
+    startedAt: nowIso(),
+    lastActivityAt: nowIso(),
+    parkedThoughts: []
+  };
 
   sessions.push(session);
   state.activeByRepo[repoKey] = session.id;
@@ -258,7 +473,19 @@ const startSession = (targetPath) => {
   console.log(c.dim("Terminal IDE - Intent - Context - Flow\n"));
   console.log(c.green("Session started."));
   printSessionSummary(session, true);
-  renderLiveTimer(session);
+  const trace = readTrace(repoKey);
+  showTraceSummary(trace);
+  clearDeliveredEchoes(repoKey, state);
+  const echoes = deliverPendingEchoes(repoKey, state);
+  if (echoes.length > 0) {
+    showEchoes(echoes);
+    saveState(state);
+  }
+  if (watch) {
+    renderLiveTimer(session);
+    return;
+  }
+  console.log(c.gray("Live timer: run `vf timer` when you want a live view."));
 };
 
 const setIntent = (text) => {
@@ -267,38 +494,66 @@ const setIntent = (text) => {
     console.error("Intent text is required.");
     return;
   }
-  const repoKey = getRepoKey(process.cwd());
-  const sessions = loadSessions();
-  const state = loadState();
-  const session = ensureActiveSession(sessions, state, repoKey);
-  if (!session) {
-    console.error("No active session. Run `vf start` first.");
-    return;
-  }
-  session.intent = { text: value, setAt: nowIso() };
-  saveSessions(sessions);
-  console.log("Intent saved.");
-};
+  const repoKey = getRepoKey(process.cwd());
+  const sessions = loadSessions();
+  const state = loadState();
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (!active.session) {
+    if (active.autoEnded) {
+      console.error("Session auto-ended due to inactivity. Run `vf start` to begin a new one.");
+      printSessionSummary(active.endedSession, false);
+      return;
+    }
+    console.error("No active session. Run `vf start` first.");
+    return;
+  }
+  active.session.intent = { text: value, setAt: nowIso() };
+  active.session.lastActivityAt = nowIso();
+  saveSessions(sessions);
+  console.log("Intent saved.");
+};
 
-const parkThought = (text) => {
-  const value = text.trim();
-  if (!value) {
-    console.error("Parked thought text is required.");
-    return;
-  }
-  const repoKey = getRepoKey(process.cwd());
-  const sessions = loadSessions();
-  const state = loadState();
-  const session = ensureActiveSession(sessions, state, repoKey);
-  if (!session) {
-    console.error("No active session. Run `vf start` first.");
-    return;
-  }
-  session.parkedThoughts.push({ text: value, createdAt: nowIso() });
-  saveSessions(sessions);
-  console.log("Thought parked.");
-};
+const parkThought = (text) => {
+  const value = text.trim();
+  if (!value) {
+    console.error("Parked thought text is required.");
+    return;
+  }
+  const repoKey = getRepoKey(process.cwd());
+  const sessions = loadSessions();
+  const state = loadState();
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (!active.session) {
+    if (active.autoEnded) {
+      console.error("Session auto-ended due to inactivity. Run `vf start` to begin a new one.");
+      printSessionSummary(active.endedSession, false);
+      return;
+    }
+    console.error("No active session. Run `vf start` first.");
+    return;
+  }
+  const thought = normalizeParkedThought({ text: value, createdAt: nowIso() });
+  active.session.parkedThoughts.push(thought);
+  if (!state.repoParkedThoughtsByRepo[repoKey]) {
+    state.repoParkedThoughtsByRepo[repoKey] = [];
+  }
+  state.repoParkedThoughtsByRepo[repoKey].push(thought);
+  active.session.lastActivityAt = nowIso();
+  saveSessions(sessions);
+  saveState(state);
+  console.log("Thought parked.");
+};
 
+const printBigTimeOnce = (elapsed) => {
+  const lines = renderBigTime(elapsed);
+  const tinted = lines.map((line, idx) => {
+    if (idx < 2) return c.cyan(line);
+    if (idx < 4) return c.blue(line);
+    return c.magenta(line);
+  });
+  console.log(tinted.join("\n"));
+};
+
 const renderLiveTimer = (session) => {
   console.log(c.cyan("== VibeFlow Timer =="));
   console.log(c.gray("Ctrl+C to stop\n"));
@@ -330,43 +585,61 @@ const status = (watch = false) => {
   const repoKey = getRepoKey(process.cwd());
   const sessions = loadSessions();
   const state = loadState();
-  const session = ensureActiveSession(sessions, state, repoKey);
-  if (session) {
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (active.session) {
     if (watch) {
-      renderLiveTimer(session);
+      active.session.lastActivityAt = nowIso();
+      saveSessions(sessions);
+      renderLiveTimer(active.session);
       return;
     }
-    printSessionSummary(session, true);
+    printSessionSummary(active.session, true);
     return;
   }
-  const last = getLastSessionForRepo(sessions, repoKey);
-  if (!last) {
-    console.log("No sessions found for this repo.");
+  if (active.autoEnded && active.endedSession) {
+    console.log(c.yellow("Session auto-ended due to inactivity."));
+    printSessionSummary(active.endedSession, false);
+    return;
+  }
+  const last = getLastSessionForRepo(sessions, repoKey);
+  if (!last) {
+    console.log("No sessions found for this repo.");
     return;
   }
   console.log("No active session. Last session:");
   printSessionSummary(last, false);
 };
 
-const resume = (targetPath) => {
-  const cwd = targetPath ? path.resolve(targetPath) : process.cwd();
-  const repoKey = getRepoKey(cwd);
-  const sessions = loadSessions();
-  const state = loadState();
-  const active = ensureActiveSession(sessions, state, repoKey);
-  if (active) {
-    console.log("Active session:");
-    printSessionSummary(active, true);
-    return;
-  }
-  const last = getLastSessionForRepo(sessions, repoKey);
-  if (!last) {
-    console.log("No sessions found for this repo.");
-    return;
-  }
-  console.log("Last session:");
-  printSessionSummary(last, false);
-};
+const resume = (targetPath) => {
+  const cwd = targetPath ? path.resolve(targetPath) : process.cwd();
+  const repoKey = getRepoKey(cwd);
+  const sessions = loadSessions();
+  const state = loadState();
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (active.session) {
+    console.log("Active session:");
+    printSessionSummary(active.session, true);
+  } else if (active.autoEnded && active.endedSession) {
+    console.log("Last session (auto-ended due to inactivity):");
+    printSessionSummary(active.endedSession, false);
+  } else {
+    const last = getLastSessionForRepo(sessions, repoKey);
+    if (!last) {
+      console.log("No sessions found for this repo.");
+    } else {
+      console.log("Last session:");
+      printSessionSummary(last, false);
+    }
+  }
+  const trace = readTrace(repoKey);
+  showTraceSummary(trace);
+  clearDeliveredEchoes(repoKey, state);
+  const echoes = deliverPendingEchoes(repoKey, state);
+  if (echoes.length > 0) {
+    showEchoes(echoes);
+    saveState(state);
+  }
+};
 
 const history = (targetPath) => {
   const cwd = targetPath ? path.resolve(targetPath) : process.cwd();
@@ -391,25 +664,33 @@ const history = (targetPath) => {
 };
 
 const timer = () => status(true);
-
+
 const end = () => {
   const repoKey = getRepoKey(process.cwd());
   const sessions = loadSessions();
   const state = loadState();
-  const session = ensureActiveSession(sessions, state, repoKey);
-  if (!session) {
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (!active.session) {
+    if (active.autoEnded) {
+      console.error("Session already auto-ended due to inactivity.");
+      printSessionSummary(active.endedSession, false);
+      return;
+    }
     console.error("No active session to end.");
     return;
   }
-  session.endedAt = nowIso();
+  active.session.endedAt = nowIso();
+  active.session.endedReason = "ended";
+  queueTimeEchoes(active.session, state);
+  writeTrace(active.session);
   saveSessions(sessions);
   delete state.activeByRepo[repoKey];
   saveState(state);
   console.log("Session ended.");
-  printSessionSummary(session, false);
+  printSessionSummary(active.session, false);
   process.exit(0);
 };
-
+
 const receipt = (id) => {
   const sessions = loadSessions();
   const repoKey = getRepoKey(process.cwd());
@@ -433,15 +714,190 @@ const receipt = (id) => {
   const durationMs = session.endedAt
     ? Date.parse(session.endedAt) - Date.parse(session.startedAt)
     : Date.now() - Date.parse(session.startedAt);
-  console.log(`Duration: ${formatDuration(durationMs)}`);
-  console.log(`Intent: ${session.intent?.text || "Not set"}`);
-  console.log(`Parked: ${session.parkedThoughts.length}`);
-};
+  console.log(`Duration: ${formatDuration(durationMs)}`);
+  console.log(`Intent: ${session.intent?.text || "Not set"}`);
+  console.log(`Parked: ${(session.parkedThoughts || []).length}`);
+  console.log(`Time Echoes: ${(session.timeEchoes || []).length}`);
+};
+
+const echoCommand = (argsList) => {
+  const repoKey = getRepoKey(process.cwd());
+  const sessions = loadSessions();
+  const state = loadState();
+  const sub = argsList[0];
+  if (!sub || sub === "list") {
+    const pending = state.pendingTimeEchoesByRepo[repoKey] || [];
+    const delivered = state.deliveredTimeEchoesByRepo[repoKey] || [];
+    if (pending.length === 0 && delivered.length === 0) {
+      console.log("No time echoes for this repo.");
+      return;
+    }
+    if (pending.length > 0) {
+      console.log(c.blue("Queued (next session):"));
+      pending.forEach((echo) => {
+        console.log(`- ${echo.id}: ${echo.text}`);
+      });
+    }
+    if (delivered.length > 0) {
+      console.log(c.magenta("Delivered (waiting for action):"));
+      delivered.forEach((echo) => {
+        console.log(`- ${echo.id}: ${echo.text}`);
+      });
+      console.log(c.gray("Use `vf echo park <id>` or `vf echo discard <id>`."));
+    }
+    return;
+  }
+  if (sub === "park" || sub === "discard") {
+    const id = argsList[1];
+    if (!id) {
+      console.error("Echo id is required.");
+      return;
+    }
+    const delivered = state.deliveredTimeEchoesByRepo[repoKey] || [];
+    const target = delivered.find((echo) => echo.id === id);
+    if (!target) {
+      console.error("Echo not found or already handled.");
+      return;
+    }
+    state.deliveredTimeEchoesByRepo[repoKey] = delivered.filter((echo) => echo.id !== id);
+    if (sub === "park") {
+      if (!state.repoParkedThoughtsByRepo[repoKey]) {
+        state.repoParkedThoughtsByRepo[repoKey] = [];
+      }
+      const thought = normalizeParkedThought({ text: target.text, createdAt: nowIso() });
+      state.repoParkedThoughtsByRepo[repoKey].push(thought);
+      const active = ensureActiveSession(sessions, state, repoKey);
+      if (active.session) {
+        active.session.parkedThoughts.push(thought);
+        active.session.lastActivityAt = nowIso();
+        saveSessions(sessions);
+      }
+      saveState(state);
+      console.log("Echo parked as a thought.");
+      return;
+    }
+    saveState(state);
+    console.log("Echo discarded.");
+    return;
+  }
+  const text = argsList.join(" ").trim();
+  if (!text) {
+    console.error("Echo message is required.");
+    return;
+  }
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (!active.session) {
+    if (active.autoEnded) {
+      console.error("Session auto-ended due to inactivity. Run `vf start` to begin a new one.");
+      printSessionSummary(active.endedSession, false);
+      return;
+    }
+    console.error("No active session. Run `vf start` first.");
+    return;
+  }
+  const echo = normalizeTimeEcho({
+    text,
+    createdAt: nowIso(),
+    deliverAt: nowIso(),
+    sourceSessionId: active.session.id
+  });
+  if (!active.session.timeEchoes) {
+    active.session.timeEchoes = [];
+  }
+  active.session.timeEchoes.push(echo);
+  active.session.lastActivityAt = nowIso();
+  saveSessions(sessions);
+  console.log("Time Echo queued for next session.");
+};
+
+const parseIdleMinutes = (value) => {
+  if (!value) {
+    return null;
+  }
+  const cleaned = value.trim().toLowerCase();
+  if (cleaned === "off" || cleaned === "disable" || cleaned === "0") {
+    return 0;
+  }
+  const match = cleaned.match(/^(\d+)(h|m)?$/);
+  if (!match) {
+    return null;
+  }
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return null;
+  }
+  if (match[2] === "h") {
+    return amount * 60;
+  }
+  return amount;
+};
+
+const setIdle = (value) => {
+  const state = loadState();
+  if (!value) {
+    const current = getIdleTimeoutMs(state);
+    if (current === 0) {
+      console.log("Idle timeout: disabled");
+      return;
+    }
+    console.log(`Idle timeout: ${state.idleTimeoutMinutes} minutes`);
+    return;
+  }
+  const minutes = parseIdleMinutes(value);
+  if (minutes === null) {
+    console.error("Invalid idle timeout. Use minutes (e.g. 90) or hours (e.g. 4h) or 'off'.");
+    return;
+  }
+  state.idleTimeoutMinutes = minutes;
+  saveState(state);
+  if (minutes === 0) {
+    console.log("Idle timeout disabled.");
+    return;
+  }
+  console.log(`Idle timeout set to ${minutes} minutes.`);
+};
+
+const touch = () => {
+  const repoKey = getRepoKey(process.cwd());
+  const sessions = loadSessions();
+  const state = loadState();
+  const active = ensureActiveSession(sessions, state, repoKey);
+  if (!active.session) {
+    if (active.autoEnded) {
+      console.error("Session auto-ended due to inactivity.");
+      printSessionSummary(active.endedSession, false);
+      return;
+    }
+    console.error("No active session. Run `vf start` first.");
+    return;
+  }
+  active.session.lastActivityAt = nowIso();
+  saveSessions(sessions);
+  console.log("Session activity refreshed.");
+};
 
-switch (command) {
-  case "start":
-    startSession(args[1]);
-    break;
+const parseStartArgs = (values) => {
+  let watch = false;
+  let targetPath = null;
+  for (const arg of values) {
+    if (arg === "--watch" || arg === "--timer") {
+      watch = true;
+      continue;
+    }
+    if (!targetPath) {
+      targetPath = arg;
+    }
+  }
+  return { watch, targetPath };
+};
+
+switch (command) {
+  case "start":
+    {
+      const parsed = parseStartArgs(args.slice(1));
+      startSession(parsed.targetPath, parsed.watch);
+    }
+    break;
   case "intent":
     setIntent(args.slice(1).join(" "));
     break;
@@ -454,18 +910,27 @@ switch (command) {
   case "timer":
     timer();
     break;
-  case "resume":
-    resume(args[1]);
-    break;
-  case "history":
-    history(args[1]);
-    break;
-  case "end":
-    end();
-    break;
-  case "receipt":
-    receipt(args[1]);
-    break;
+  case "resume":
+    resume(args[1]);
+    break;
+  case "history":
+    history(args[1]);
+    break;
+  case "idle":
+    setIdle(args[1]);
+    break;
+  case "touch":
+    touch();
+    break;
+  case "end":
+    end();
+    break;
+  case "receipt":
+    receipt(args[1]);
+    break;
+  case "echo":
+    echoCommand(args.slice(1));
+    break;
   case "help":
   case "-h":
   case "--help":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibeflow-cli",
-  "version": "0.1.1",
-  "description": "VibeFlow CLI — intent, context, and session memory for any repo.",
+  "version": "0.1.3",
+  "description": "VibeFlow CLI - intent, context, and session memory for any repo.",
   "author": "Dev Kuns (https://github.com/atobouh)",
   "license": "MIT",
   "type": "commonjs",