prjct-cli 1.6.13 → 1.7.1

package/CHANGELOG.md

@@ -1,12 +1,70 @@
 # Changelog
 
-## [1.6.13] - 2026-02-07
+## [1.7.1] - 2026-02-07
 
-### Refactoring
+### Bug Fixes
+
+- add Zod validation on all storage reads (PRJ-279) (#140)
+
+
+## [1.7.1] - 2026-02-07
+
+### Bug Fix
+- **Add Zod validation on all storage reads (PRJ-279)**: Created `safeRead<T>()` utility that wraps `JSON.parse` + `schema.safeParse()`. All 5 `StorageManager` subclasses (state, queue, ideas, shipped, metrics) now validate reads against their Zod schemas. Corrupted files produce a logged warning + `.backup` file instead of silently crashing downstream.
+
+### Implementation Details
+Created `core/storage/safe-reader.ts` with a `ValidationSchema` interface decoupled from Zod generics to avoid strict type parameter matching. The `StorageManager` base class accepts an optional schema via constructor — subclasses pass their Zod schema with a single import + arg change. `safeRead` returns the raw parsed JSON (not Zod-transformed `result.data`) to preserve extra fields for forward compatibility. Also fixed `ShippedJsonSchema` which used `items` instead of `shipped` (pre-existing schema bug), and made `changes` optional to match actual data.
 
-- remove unused templates and dead code (PRJ-293) (#138)
-- remove unused templates and dead code (PRJ-293)
+### Learnings
+- Zod's default `strip` mode silently drops unknown keys from `result.data` — must return raw JSON to preserve extra state.json fields (projectId, stack, domains, etc.)
+- `ShippedJsonSchema` had `items` instead of `shipped` as the array key — pre-existing schema/data mismatch
+- `ValidationSchema` interface avoids Zod generic constraints while still providing type-safe validation
+
+### Test Plan
+
+#### For QA
+1. Create a valid `state.json` — verify it reads correctly with no warnings
+2. Corrupt a storage file with invalid JSON — verify `.backup` is created and defaults returned
+3. Write valid JSON with wrong schema — verify `.backup` and defaults
+4. Add extra fields not in schema — verify they are preserved after read
+5. Run `bun test` — verify all 438 tests pass (16 new for `safeRead`)
+
+#### For Users
+**What changed:** Storage reads are now validated against Zod schemas. Corrupted files no longer cause silent crashes.
+**How to use:** No action needed — automatic.
+**Breaking changes:** None.
 
+## [1.7.0] - 2026-02-07
+
+### Features
+
+- use relative timestamps to reduce token waste (PRJ-274) (#139)
+- use relative timestamps to reduce token waste (PRJ-274)
+
+## [1.6.16] - 2026-02-07
+
+### Improvement
+- **Use relative timestamps to reduce token waste (PRJ-274)**: Added `toRelative()` function using `date-fns` `formatDistanceToNowStrict`. Replaced raw ISO-8601 timestamps in Markdown context files (`now.md`, `ideas.md`, `shipped.md`) with human-readable relative time ("5 minutes ago", "3 days ago"). JSON storage retains full ISO timestamps — no data loss.
+
+### Implementation Details
+Added `date-fns` as a dependency and created a thin `toRelative(date)` wrapper around `formatDistanceToNowStrict` in `core/utils/date-helper.ts`. Updated `toMarkdown()` in `state-storage.ts` (Started/Paused fields), `ideas-storage.ts` (all 3 sections: pending, converted, archived), and `shipped-storage.ts` (ship date per entry). 6 new unit tests added covering minutes, hours, days, months, Date objects, and ISO string inputs.
+
+### Learnings
+- `date-fns` `formatDistanceToNowStrict` gives exact units ("5 minutes ago" not "about 5 minutes ago") — better for token efficiency
+- Tests need `setSystemTime()` from `bun:test` since `formatDistanceToNowStrict` uses system clock internally
+
+### Test Plan
+
+#### For QA
+1. Run `bun test core/__tests__/utils/date-helper.test.ts` — verify all 55 tests pass (6 new for `toRelative`)
+2. Run `bun run build` — verify build succeeds
+3. Run `prjct sync` — verify `context/now.md` shows relative timestamps instead of raw ISO
+4. Check `ideas.md` and `shipped.md` for relative date format
+
+#### For Users
+**What changed:** Timestamps in context files now show "5 minutes ago", "3 days ago" instead of raw ISO-8601 strings.
+**How to use:** No action needed — automatic.
+**Breaking changes:** None.
 
 ## [1.6.15] - 2026-02-07
 

package/core/__tests__/storage/safe-reader.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Safe Reader Tests
+ *
+ * Tests for Zod-validated storage reads:
+ * - Valid data passes through
+ * - Corrupted JSON creates .backup + returns null
+ * - Valid JSON with wrong schema creates .backup + returns null
+ * - Missing files return null (no backup)
+ * - Extra fields are preserved (forward compatibility)
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { z } from 'zod'
+import { safeRead } from '../../storage/safe-reader'
+
+// =============================================================================
+// Test Schema
+// =============================================================================
+
+const TestSchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  items: z.array(z.string()),
+})
+
+type TestData = z.infer<typeof TestSchema>
+
+// =============================================================================
+// Setup
+// =============================================================================
+
+let tmpDir: string
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'prjct-safe-reader-test-'))
+})
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true })
+})
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('safeRead', () => {
+  describe('valid data', () => {
+    it('should return validated data for valid JSON matching schema', async () => {
+      const filePath = path.join(tmpDir, 'valid.json')
+      const data: TestData = { name: 'test', count: 42, items: ['a', 'b'] }
+      await fs.writeFile(filePath, JSON.stringify(data, null, 2))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toEqual(data)
+    })
+
+    it('should preserve extra fields not in schema', async () => {
+      const filePath = path.join(tmpDir, 'extra-fields.json')
+      const data = {
+        name: 'test',
+        count: 1,
+        items: [],
+        extraField: 'preserved',
+        nested: { deep: true },
+      }
+      await fs.writeFile(filePath, JSON.stringify(data, null, 2))
+
+      const result = await safeRead<typeof data>(filePath, TestSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.name).toBe('test')
+      expect(result!.extraField).toBe('preserved')
+      expect(result!.nested).toEqual({ deep: true })
+    })
+
+    it('should not create .backup for valid data', async () => {
+      const filePath = path.join(tmpDir, 'no-backup.json')
+      const data: TestData = { name: 'ok', count: 0, items: [] }
+      await fs.writeFile(filePath, JSON.stringify(data))
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(false)
+    })
+  })
+
+  describe('missing files', () => {
+    it('should return null for non-existent file', async () => {
+      const result = await safeRead<TestData>(path.join(tmpDir, 'missing.json'), TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should not create .backup for missing file', async () => {
+      const filePath = path.join(tmpDir, 'missing.json')
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(false)
+    })
+  })
+
+  describe('corrupted JSON', () => {
+    it('should return null for malformed JSON', async () => {
+      const filePath = path.join(tmpDir, 'malformed.json')
+      await fs.writeFile(filePath, 'not valid json {{{')
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should create .backup for malformed JSON', async () => {
+      const filePath = path.join(tmpDir, 'malformed.json')
+      const badContent = 'not valid json {{{'
+      await fs.writeFile(filePath, badContent)
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backup = await fs.readFile(`${filePath}.backup`, 'utf-8')
+      expect(backup).toBe(badContent)
+    })
+
+    it('should return null for empty file', async () => {
+      const filePath = path.join(tmpDir, 'empty.json')
+      await fs.writeFile(filePath, '')
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('valid JSON with wrong schema', () => {
+    it('should return null when required field is missing', async () => {
+      const filePath = path.join(tmpDir, 'missing-field.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test' })) // missing count and items
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should create .backup when schema validation fails', async () => {
+      const filePath = path.join(tmpDir, 'wrong-schema.json')
+      const data = { name: 123, count: 'not a number', items: 'not an array' }
+      await fs.writeFile(filePath, JSON.stringify(data))
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(true)
+    })
+
+    it('should return null when field has wrong type', async () => {
+      const filePath = path.join(tmpDir, 'wrong-type.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 42, count: 1, items: [] }))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should return null when array contains wrong types', async () => {
+      const filePath = path.join(tmpDir, 'wrong-array.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test', count: 1, items: [1, 2, 3] }))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('optional fields and defaults', () => {
+    it('should handle schema with optional fields', async () => {
+      const OptionalSchema = z.object({
+        name: z.string(),
+        description: z.string().optional(),
+      })
+
+      const filePath = path.join(tmpDir, 'optional.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test' }))
+
+      const result = await safeRead<z.infer<typeof OptionalSchema>>(filePath, OptionalSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.name).toBe('test')
+      expect(result!.description).toBeUndefined()
+    })
+
+    it('should handle schema with nullable fields', async () => {
+      const NullableSchema = z.object({
+        currentTask: z.object({ id: z.string() }).nullable(),
+        lastUpdated: z.string(),
+      })
+
+      const filePath = path.join(tmpDir, 'nullable.json')
+      await fs.writeFile(filePath, JSON.stringify({ currentTask: null, lastUpdated: '2026-01-01' }))
+
+      const result = await safeRead<z.infer<typeof NullableSchema>>(filePath, NullableSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.currentTask).toBeNull()
+    })
+  })
+
+  describe('integration with StorageManager pattern', () => {
+    it('should work with real StateJsonSchema', async () => {
+      // Import the actual schema used in production
+      const { StateJsonSchema } = await import('../../schemas/state')
+
+      const filePath = path.join(tmpDir, 'state.json')
+      const stateData = {
+        currentTask: null,
+        lastUpdated: '2026-02-07T00:00:00.000Z',
+        // Extra fields that exist in real state.json but not in schema
+        projectId: 'test-123',
+        stack: { language: 'TypeScript', framework: 'Hono' },
+      }
+      await fs.writeFile(filePath, JSON.stringify(stateData, null, 2))
+
+      const result = await safeRead<typeof stateData>(filePath, StateJsonSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.currentTask).toBeNull()
+      expect(result!.projectId).toBe('test-123') // Extra field preserved
+    })
+
+    it('should reject corrupted state data', async () => {
+      const { StateJsonSchema } = await import('../../schemas/state')
+
+      const filePath = path.join(tmpDir, 'bad-state.json')
+      // currentTask should be an object or null, not a number
+      const badData = { currentTask: 42, lastUpdated: '2026-02-07' }
+      await fs.writeFile(filePath, JSON.stringify(badData))
+
+      const result = await safeRead(filePath, StateJsonSchema)
+
+      expect(result).toBeNull()
+      // Backup should exist
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(true)
+    })
+  })
+})

package/core/__tests__/utils/date-helper.test.ts

@@ -21,6 +21,7 @@ import {
   isToday,
   isWithinLastDays,
   parseDate,
+  toRelative,
 } from '../../utils/date-helper'
 
 describe('DateHelper', () => {
@@ -402,4 +403,47 @@ describe('DateHelper', () => {
       expect(original.getMinutes()).toBe(30)
     })
   })
+
+  describe('toRelative', () => {
+    it('should show minutes for dates within 1 hour', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const fiveMinAgo = '2025-10-15T11:55:00.000Z'
+      expect(toRelative(fiveMinAgo)).toBe('5 minutes ago')
+      setSystemTime()
+    })
+
+    it('should show hours for dates within 24 hours', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const threeHoursAgo = '2025-10-15T09:00:00.000Z'
+      expect(toRelative(threeHoursAgo)).toBe('3 hours ago')
+      setSystemTime()
+    })
+
+    it('should show days for dates within 7 days', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const twoDaysAgo = '2025-10-13T12:00:00.000Z'
+      expect(toRelative(twoDaysAgo)).toBe('2 days ago')
+      setSystemTime()
+    })
+
+    it('should show months for dates older than 30 days', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const twoMonthsAgo = '2025-08-15T12:00:00.000Z'
+      expect(toRelative(twoMonthsAgo)).toBe('2 months ago')
+      setSystemTime()
+    })
+
+    it('should accept Date objects', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const date = new Date('2025-10-15T11:00:00.000Z')
+      expect(toRelative(date)).toBe('1 hour ago')
+      setSystemTime()
+    })
+
+    it('should accept ISO string timestamps', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      expect(toRelative('2025-10-14T12:00:00.000Z')).toBe('1 day ago')
+      setSystemTime()
+    })
+  })
 })

package/core/schemas/shipped.ts

@@ -56,7 +56,7 @@ export const ShippedItemSchema = z.object({
   type: ShipTypeSchema,
   agent: z.string().optional(), // "fe+be", "be", "fe"
   description: z.string().optional(),
-  changes: z.array(ShipChangeSchema),
+  changes: z.array(ShipChangeSchema).optional(),
   codeSnippets: z.array(z.string()).optional(),
   commit: CommitInfoSchema.optional(),
   codeMetrics: CodeMetricsSchema.optional(),
@@ -69,7 +69,7 @@ export const ShippedItemSchema = z.object({
 })
 
 export const ShippedJsonSchema = z.object({
-  items: z.array(ShippedItemSchema),
+  shipped: z.array(ShippedItemSchema),
   lastUpdated: z.string(),
 })
 
@@ -104,6 +104,6 @@ export const safeParseShipped = (data: unknown) => ShippedJsonSchema.safeParse(d
 // =============================================================================
 
 export const DEFAULT_SHIPPED: ShippedJson = {
-  items: [],
+  shipped: [],
   lastUpdated: '',
 }

package/core/storage/ideas-storage.ts

@@ -6,13 +6,14 @@
  */
 
 import { generateUUID } from '../schemas'
+import { IdeasJsonSchema } from '../schemas/ideas'
 import type { Idea, IdeaPriority, IdeaStatus, IdeasJson } from '../types'
-import { getTimestamp } from '../utils/date-helper'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class IdeasStorage extends StorageManager<IdeasJson> {
   constructor() {
-    super('ideas.json')
+    super('ideas.json', IdeasJsonSchema)
   }
 
   protected getDefault(): IdeasJson {
@@ -45,10 +46,10 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     lines.push('## Brain Dump')
     if (pending.length > 0) {
       pending.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
+        const rel = toRelative(idea.addedAt)
         const tags = idea.tags.length > 0 ? ` ${idea.tags.map((t) => `#${t}`).join(' ')}` : ''
         const priority = idea.priority !== 'medium' ? ` [${idea.priority.toUpperCase()}]` : ''
-        lines.push(`- ${idea.text}${priority} _(${date})_${tags}`)
+        lines.push(`- ${idea.text}${priority} _(${rel})_${tags}`)
       })
     } else {
       lines.push('_No pending ideas_')
@@ -59,9 +60,9 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     if (converted.length > 0) {
       lines.push('## Converted')
       converted.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
+        const rel = toRelative(idea.addedAt)
         const feat = idea.convertedTo ? ` \u2192 ${idea.convertedTo}` : ''
-        lines.push(`- \u2713 ${idea.text}${feat} _(${date})_`)
+        lines.push(`- \u2713 ${idea.text}${feat} _(${rel})_`)
       })
       lines.push('')
     }
@@ -70,8 +71,8 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     if (archived.length > 0) {
       lines.push('## Archived')
       archived.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
-        lines.push(`- ${idea.text} _(${date})_`)
+        const rel = toRelative(idea.addedAt)
+        lines.push(`- ${idea.text} _(${rel})_`)
       })
       lines.push('')
     }

package/core/storage/metrics-storage.ts

@@ -18,13 +18,14 @@ import {
   estimateCostSaved,
   formatCost,
   type MetricsJson,
+  MetricsJsonSchema,
 } from '../schemas/metrics'
 import { getTimestamp } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class MetricsStorage extends StorageManager<MetricsJson> {
   constructor() {
-    super('metrics.json')
+    super('metrics.json', MetricsJsonSchema)
   }
 
   protected getDefault(): MetricsJson {

package/core/storage/queue-storage.ts

@@ -7,12 +7,13 @@
 
 import { generateUUID } from '../schemas'
 import type { Priority, QueueJson, QueueTask, TaskSection } from '../schemas/state'
+import { QueueJsonSchema } from '../schemas/state'
 import { getTimestamp } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class QueueStorage extends StorageManager<QueueJson> {
   constructor() {
-    super('queue.json')
+    super('queue.json', QueueJsonSchema)
   }
 
   protected getDefault(): QueueJson {

package/core/storage/safe-reader.ts

@@ -0,0 +1,105 @@
+/**
+ * Safe Reader
+ *
+ * Wraps JSON.parse + Zod schema.safeParse() for validated storage reads.
+ * On corruption: logs warning, creates .backup, returns null.
+ *
+ * Uses schema for structural validation only — returns the raw parsed
+ * data (not Zod-transformed) to preserve extra fields that may exist
+ * in storage files but aren't in the schema yet (forward compatibility).
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'node:fs/promises'
+import type { ZodError } from 'zod'
+import { isNotFoundError } from '../types/fs'
+
+/**
+ * Minimal interface for Zod-like validation.
+ * Decoupled from Zod generics to avoid strict type parameter matching.
+ */
+export interface ValidationSchema {
+  safeParse(data: unknown): { success: boolean; error?: ZodError }
+}
+
+/**
+ * Read and validate a JSON file against a Zod schema.
+ *
+ * Flow:
+ * 1. Read file → if missing, return null
+ * 2. JSON.parse → if malformed JSON, backup + return null
+ * 3. schema.safeParse → if valid, return raw parsed data as T
+ * 4. If invalid but parseable JSON, backup + return null
+ *
+ * Returns raw parsed JSON (not Zod-transformed) to preserve extra fields.
+ *
+ * @returns Validated data or null if file is missing/corrupted
+ */
+export async function safeRead<T>(filePath: string, schema: ValidationSchema): Promise<T | null> {
+  let content: string
+
+  // Step 1: Read file
+  try {
+    content = await fs.readFile(filePath, 'utf-8')
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return null
+    }
+    throw error
+  }
+
+  // Step 2: JSON.parse
+  let raw: unknown
+  try {
+    raw = JSON.parse(content)
+  } catch {
+    // Malformed JSON — backup and return null
+    await createBackup(filePath, content)
+    logCorruption(filePath, 'Malformed JSON')
+    return null
+  }
+
+  // Step 3: Validate against schema
+  const result = schema.safeParse(raw)
+  if (result.success) {
+    // Return raw data to preserve extra fields not in schema
+    return raw as T
+  }
+
+  // Step 4: Validation failed — backup and return null
+  await createBackup(filePath, content)
+  logCorruption(filePath, formatZodError(result.error!))
+  return null
+}
+
+/**
+ * Create a .backup of a corrupted file
+ */
+async function createBackup(filePath: string, content: string): Promise<void> {
+  const backupPath = `${filePath}.backup`
+  try {
+    await fs.writeFile(backupPath, content, 'utf-8')
+  } catch {
+    // Best-effort backup — don't throw if it fails
+  }
+}
+
+/**
+ * Log corruption warning to stderr
+ */
+function logCorruption(filePath: string, reason: string): void {
+  console.error(`[prjct] Warning: Corrupted storage file: ${filePath}`)
+  console.error(`[prjct]   Reason: ${reason}`)
+  console.error(`[prjct]   A .backup file has been created. Returning defaults.`)
+}
+
+/**
+ * Format Zod error into a readable string
+ */
+function formatZodError(error: ZodError): string {
+  return error.issues
+    .slice(0, 3)
+    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+    .join('; ')
+}

package/core/storage/shipped-storage.ts

@@ -6,13 +6,14 @@
  */
 
 import { generateUUID } from '../schemas'
+import { ShippedJsonSchema } from '../schemas/shipped'
 import type { ShippedFeature, ShippedJson } from '../types'
-import { getTimestamp } from '../utils/date-helper'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class ShippedStorage extends StorageManager<ShippedJson> {
   constructor() {
-    super('shipped.json')
+    super('shipped.json', ShippedJsonSchema)
   }
 
   protected getDefault(): ShippedJson {
@@ -72,13 +73,10 @@ class ShippedStorage extends StorageManager<ShippedJson> {
         .sort((a, b) => new Date(b.shippedAt).getTime() - new Date(a.shippedAt).getTime())
 
       ships.forEach((ship) => {
-        const date = new Date(ship.shippedAt).toLocaleDateString('en-US', {
-          month: 'short',
-          day: 'numeric',
-        })
+        const rel = toRelative(ship.shippedAt)
         const version = ship.version ? ` v${ship.version}` : ''
         const duration = ship.duration ? ` (${ship.duration})` : ''
-        lines.push(`- **${ship.name}**${version}${duration} - ${date}`)
+        lines.push(`- **${ship.name}**${version}${duration} - ${rel}`)
         if (ship.description) {
           lines.push(`  _${ship.description}_`)
         }

package/core/storage/state-storage.ts

@@ -16,13 +16,14 @@ import type {
   Subtask,
   SubtaskSummary,
 } from '../schemas/state'
-import { getTimestamp } from '../utils/date-helper'
+import { StateJsonSchema } from '../schemas/state'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { md } from '../utils/markdown-builder'
 import { StorageManager } from './storage-manager'
 
 class StateStorage extends StorageManager<StateJson> {
   constructor() {
-    super('state.json')
+    super('state.json', StateJsonSchema)
   }
 
   protected getDefault(): StateJson {
@@ -52,7 +53,7 @@ class StateStorage extends StorageManager<StateJson> {
         const task = data.currentTask!
         m.bold(task.description)
           .blank()
-          .raw(`Started: ${task.startedAt}`)
+          .raw(`Started: ${toRelative(task.startedAt)}`)
           .raw(`Session: ${task.sessionId}`)
           .maybe(task.featureId, (m, id) => m.raw(`Feature: ${id}`))
 
@@ -122,7 +123,7 @@ class StateStorage extends StorageManager<StateJson> {
         m.hr()
           .h2('Paused')
           .bold(prev.description)
-          .raw(`Paused: ${prev.pausedAt}`)
+          .raw(`Paused: ${toRelative(prev.pausedAt)}`)
           .maybe(prev.pauseReason, (m, reason) => m.raw(`Reason: ${reason}`))
           .blank()
           .italic('Use /p:resume to continue')